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► The Widest Range of 32-bit Intel x86 Platfoims 

32-bit DOS, 32-bit Windows, OS/2 2.0, AutoCAD ADS 


► The Industry^ Leading Code Optimizer 

Advanced global optimizer with new 486 optimizations 

► The Most Comprehensive Toolset 

Debugger, profiler, protected-mode compiler and linker, 
32-bit DOS extender with royalty-free run-time, licensed 
components from Microsoft SDK, and more 

► The Best Value in 32-Bit Tools: $895* ^Se£ 


Unleash 32-bit Power! 

WATCOM C9.0/386 lets you exploit the two key 32-hit per¬ 
formance benefits. The 32-bit flat memory model simplifies 
memory management and lets applications address beyond 
the 640K limit. Powerful 32-bit instruction processing delivers 
a significant speed advantage: typically at least a 2x speedup. 

You Get: 

► 100% ANSI and SAA compatible: C9.0/386 passes all Plum Hall 
Validation Suite tests 

► Extensive Microsoft compatibility simplifies porting of!6-bit code 

► Royalty-free run-time for 32-bit DOS. Windows and OS/2 apps 

► Comprehensive toolset includes debugger, linker, profiler and more 

► DOS extender support for Rational. Pliar Lap and Ergo 

► Run-time compatible with WATCOM FORTRAN 77/386 

32-bit DOS support includes the DOS/4GW 32-bit DOS extender by 
Rational Systems with royalty-free runtime license 

► Virtual Memory support up to 32Mb 

32-bit Windows support enables development and debugging of 
true 32-bit Gl'I applications and DLL's, 

► Includes licensed Microsoft SDK components 

32-bit OS/2 2.0 support includes development for multiple target 
environments including OS/2 2.(L 32-bit DOS and 32-bit Windows 

► Access to full OS/2 2.0 API including Presentation Manager 

► Integrated with IBM Workframe/2 Environment 

AutoCAD ADS and ADI Development; Everything you need to 
develop and debug ADS and ADI applications for AutoCAD Release 11 

Novell’s Network C for NLM 's SDK includes C/386 


The Industry’s Choice. 

Autodesk. Robert Wenig, Manager. AutoCAD for Windows: 

At Autodesk, were using WATCOM C/386 in the development 
of strategic new products since it gives us a competitive edge 
through early access to new technologies. We also highly 
recommend WATCOM C 386 to third party AutoCAD add-on 
(ADS and ADI) developers," 

FOX Software. David Fulton. President: "FoxPro 2.0 itself is 
written in WATCOM C. and takes advantage of its many superior 
features. Optimizing for either speed or compactness is not 
uncommon, but to accomplish both was quite remarkable," 

GO. Robert Can, Vice President of Software: ".After looking at the 
32-bit Intel 80x86 tools available in the industry. WATCOM C was 
the best choice. Key factors in our decision were performance, 
functionality, reliability and technical support.” 

IBM. John Soyring, Director of OS/2 Softit are Deretoper Programs: 
“IBM and W ATCOM are working together closely to integrate these 
compilers with the OS/2 2.0 Programmer's Workbench." 

Lotus. David Reed, Chief Scientist and Vice President, Pen-Based 
Applications: "in new- product development we’re working with 
WATCOM C because of superior code optimization, responsive 
support, and timely delivery of technologies important to us like 
p-code and support for GO Corp’s. PenPoint." 

Novell. Nancy Woodward, VP and G.M., Development Products: 
"We searched the industry tor the best 386 C. compiler technology 
to incorporate with our developer toolkits. Our choice was 
WATCOM." 
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► 100% ANSI C optimizing compiler 

► Protected-mode compiler ► OS/2 
hosted-compiler ► Royalty-free DOS 
extender with VMM support ► Licensed 
components of the Microsoft Windows SDK 

► Interactive source-level debugger ► Linker 

► Protected-mode linker ► OS/2-hosted linker ► Profiler 

► Object code librarian ► Object code disassembler ► MAKE 
facility ► Patch facility ► Object module convert utility 

► Windows supervisor ► Bind facility for Windows applications 

► 32-bit run-time library* object code ► Special 32-bit libraries 
for Windows API ► Graphics library- for Extended DOS 
applications ► 32-bit Run-time libraries for Windows ► 32-bit 
Run-time libraries tor OS/2 
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WORLD/ 
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BEST IN 
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Microsoft 

WINDOWS. 


EDITORS' 

CHOICE 


September i 3 . 
Waters* C.'rtrwr 6 S 


Special Offer 

Buy WATCOM C9.0/386 and you’ll be eligible to obtain: 

WATCOM C9.0 Delta Pack provides you with the tools necessary to 
develop and debug 16-bit applications for DOS, Windows, and OS/2. 
Only $99. (S495 comparative separate cost) 

WATCOM FORTRAS 771386 Delta Pack provides you with 
everything necessary to develop and debug 3 2-bit FORTRAN 
applications for extended DOS, 32-bit Windows and OS/2 2.0. 
Only $399. (S895 comparative separate cost) 


WAT »wgri 1-800-265-4555 

The Leader in 32-bit Development Tools 

415 Phillip Sfreel, Waterloo. Ontario. Canada 
Telephone (S19) BB6-3700. Fax (519) 747-4971 

■Price does not include freight and laines where applicable Authorized dealers may sell inr less 

WATCOM C amt Lightning Device are trademarks ol WATCOM Systems I Fit 

D0&/4G and DQftiSM are trademarks of ftatipnai Systems Inc 

Oiher trademarks are ihe properties ol their respective owners 

Copyright 1992 WATCOM Products Inc 
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Spend three days 
at the ’92 

Embedded Systems 
Conference. 


Spend the year 
using what you learned. 


H elpful. Inspiring l op Notch. 

Excellent, These are just some 
of the words our past attendees 
use to describe the Embedded Systems 
Conference faculty. In just three days 
you'll find answers to the toughest 
questions you face presented by leaders in 
the embedded development community. 
Faculty' who know your job is becoming 
more complex; who work everyday on 
real workable solutions to the roughest 
problems you face. People like Larry 
Constantine, Steve Mel lor, Paul Ward, 
Derek Hatley, Imtiaz Pirbhai, 

P.J. Plaugcr, and Michael Slater, 

Build Your Own Program. 

Customize your own program by 
choosing from over 75 lectures and 
workshops that cover a wide range of 
issues in embedded development. You 5 ]I 
get rop notch advice on real-time 
programming, CASE and object-oriented 
methodologies, embedded project 
management, programming languages, 
debugging and algorithms and much 
more. 


Tut Fourth 

Annual Embedded Systems 
Conference 

September 21-24, 1992 

San ta Clara Convention Center 
Santa Ciara, California 



Attendee i . ■. rTj chuQtrftmn atxr 75 

itl ltd by tb? kadetr in 

ftti hrddrtl t/i'tYlnp»trnt, 


Try Out The Latest 
Technology At The 
Emhedded Systems 
Development Products 
Exhibition. 

The Embedded Systems 
Conference will also be the 
sire of the largest most highly 
targeted exhibition of 
embedded development 
products and services. 
Nowhere else will you find all 
the latest tools and utilities on 
display at one time. 



The Santa Qara Canvemicm Censor r- 
located ns the htutt of 
< \i!hvn l 'alley. 


You’ll Come Away With 
New Ideas That 
Translate Directly Into 
Increased Productivity'. 

Most importantly, the 
Embedded Systems Conference 
is a peer environment that 
fosters dynamic exchange of 
vital information, ideas, and 
insights. You’ll find professional 
excellence Throughout the 
conference; in die lectures and 
workshops, on the floor of the 



Oir? !20 rxlnfafttn will hr ditrunafing 
, it tnug trig c toafs and utilities. 


exposition, in the tutorials, 
and in informal receptions 
and hospitality events. And 
youll get it all in three days. 

Phone us, fax us or mail 
us today for more 
information. 

TEL; (415)905-2354 
FAX: (415)905-2220 


““ - ~ --- -- -- “"““ibsy] 

“I YES! Pleas* send me more information about the Embedded Systems Conference. 

Name_lie__ 

Company_ 

Address.__ _ _ 

City ___State_Bp_ [ 

Phone f_)__ FAX („ _ ) _ j 

Send info on; □ attending “I exhibit^ Please also send info toc___ 

Mai or FW to- EfitwIdHl Systems Cadetence Mier f mim Inc. \ 
P.0 8oi mi Sw fantisa, 01M12MS4—TE (415} S0^2iS4: FAX m) SOS-2220 i 

I____ _ ______ i 
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Editor's 

Comments 



W hat happened to the Personal Systems 
Developer ? No doubt you have already 
noticed a few changes. 

Last spring, the long-awaited OS/2™ 2,0 
became generally available to our customers. 
This rebirth of the operating system coincided 
with many other changes at IBM, including an 
improved and expanded support program for 
our software developers. This magazine has 
been a key part of IBM's OS/2 support from 
the beginning. Now we're making a few 
changes of our own. 

A New Look 

Our new publisher is Miller Freeman Inc. in 
San Francisco, California, publisher of 
Computer Language, UNIX Review, MN 
Magazine, and AI Expert . We are excited about 
this new partnership and the benefits it will 
bring to both the magazine and our readers. 

A New Name 

We have always been an all-OS/2 magazine. 
Now it's time to let our name reflect our true 
colors. 

Tell Us More 

We have been reaching OS/2 application 
developers through several channels: our own 
Developer Assistance Program, IBM's 
Mechanicshurg Distribution Center, individual 
subscriptions, and a variety of classes, 
seminars, forums, and trade shows. But we 
still don't know who you are. If you received a 
questionnaire with this issue, please take the 
time to fill it out and return it to us. We need to 
know who you are and how we're doing. 

What kind of work do you do? Which articles 
are most useful to you in your work? What 
new topics do you want to see? Do you have a 


success story to share? Here's your chance to 
help us make this magazine the best it can be. 

Welcome Aboard 

Many of you are discovering us for the first 
time. That's because we are launching our retail 
sales campaign, taking OS/2 Developer to a 
variety of computer and book stores. 

You've probably noticed another change: paid 
advertisements. We are opening OS/2 Developer 
to independent software vendors, OEMs, and 
other partners who have products of interest to 
OS/2 application developers. Software tools 
has always been a popular topic in these pages, 
and we expect the ads to announce new and 
useful tools, utilities, and other products to 
enhance your applications. 

As one of my colleagues remarked recently, it's 
time for our "baby" to leave the nest and make 
its way in the world. As with OS/2 itself, we 
know we have a good product that can help 
thousands of software developers. To our long¬ 
time readers: thanks for your support and 
encouragement. To our new readers: we're 
glad to have you with us; don't be shy about 
telling us what you think. 

There's one more change. Starting with the next 
issue, we're going to add a "Letters to the 
Editor" column. Here's a chance to comment 
on our articles, ask questions of our writers, 
and express your opinions about OS/2. Send 
your letters to me at MCI Mail (274-8797) or fax 
(407) 443-4233. 



Dick Conklin 
Editor 



Dick Conklin 


A new OS/2; 
a new magazine 
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Spotlight 

Spotlight on the OS/2 2.0 
Development Team 


by Mary A. Wright 

In size, OS/2 2.0 is an awesome product, 
containing: 

*21 disks (33 MB) for the base operating system 
and its on-line help information and 400 pages of 
hardcopy documentation 

* 9 disks (24 MB) for the toolkit (sample programs , 
development tools , and on-line programming 
information) 

• 8000 pages of hardcopy programming 
information in the technical library. 

In functionality, OS/2 2.0 is exciting, offering an 
integrating platform with an object-oriented user 
interface for DOS t Windows™, and OS/2 
applications. 

On March 31, r 1992, OS/2 2.0 officially went 
golden. Sleepless nights of building driver after 
driver until all was right were over. Clusters of 
colored balloons, carrying invitations to celebrate 
the moment, glided down the halls of the Personal 
Systems Programming Center (PSPC) in Boca 
Raton, Florida. It was a moment of joy, relief and 
great expectations. The OS/2 team had met the 
challenge and won. 

The Spotlight article in each issue of this magazine 
usually features a key OS/2 software vendor and 
that vendor's experience with OS/2. In this issue, 
we depart from our usual format and spotlight the 
PSPC 's OS/2 development team. 

TEAM BACKGROUND 

T he OS/2 development team consists of 
men and women of diverse age, 
education, and experience. It's a fairly young 


group of people. Most joined IBM directly 
after graduation from college. Most hold a 
bachelor's degree or equivalent in a scientific 
field. Some, like Greg Simco, technical lead for 
the OS/2 File System, are working toward 
doctoral degrees in computer science. 

Although many team members have degrees 
in computer science, some have found their 
way into the world of the PC after academic 
work in other subjects. Bill Bodin, staff 
programmer and technical lead for OS/2 
Console I/O, received his bachelor's degree in 
biology from the Uni versity of Georgia* After 
getting involved with PCs while working at 
the university engineering center as a 
biochemical lab technician, he became 
software technician for the center and was 
involved in the design, coding, and 
implementation of several real-time systems. 

Several OS/2 team 
members had 
previous 
experience in 
operating system 
development. Scott 
Jones, an advisory 
programmer for 
PM Graphics, 
worked on the 
Series/1 Realtime 
Programming 
System (RPS). Steve 
Glazer, staff 
programmer and team lead for Functional 
Verification Test, worked on the Series/1 
Event Driven Executive (EDX) operating 
system in communications. 

Before working on the OS/2 operating system, 
many team members had no experience with a 
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project of such magnitude and complexity. 
Craig Bennett, senior associate programmer 
and team lead for Installation Services, worked 
on IBM hardware design tools, Terri Beck, staff 
programmer and former team lead for W1N- 
05/2, came to IBM from Encore Computer 
Systems, where, she says, "The entire 
organization—planning, design, development, 
testing, documentation, packaging, customer 
support, etc—was approximately the size of 
the OS/2 development organization. The work 
and problems were similar, but on a smaller 
scale/' 

Like many Floridians, the OS/2 team members 
come from across the country and the world. 
Not everyone on the team, however, resides in 
Florida. Programmers from other IBM 
locations came to the PSPC on temporary 
assignments. Programming talent was also 
imported from outside the U.S. Chris Andrew, 
David Kerr, Mike Perks, Jeff Moreland, Kelvin 
Lawrence, and Donald Hobem are all PM 
programmers from the U.K. 

TEAM RESPONSIBILITIES 

OS/2 team assignments covered the wide 
range of components that make up the 
operating system. Terri Beck was responsible 
for coordinating seamless Windows in OS/2, 
Scott Jones helped write the 32-hit graphics 
engine. Bill Bodin, the former biologist, was 
responsible for OS/2's virtual video drivers. 

In many cases, 
team members 
worked on 
multiple 

components of the 
operating system, 
Phil Doragh, senior 
associate 
programmer for 
OS/2 File Systems, 
was the primary 
developer for the 
HPFS file system 
and a secondary 
developer for the 
Boot Manager, the Installable File System 
Mechanism, the FAT and HPFS disk utilities, 
and System Boot. Craig Bennett worked on the 
design, prototype, and code for the system 


installation program, as well as the Toolkit 
installation program. Steve Glazer worked on 
design and development of the Floating Point 
Emulator Support and on the verification tests 
for memory management, kernel services, and 
asynchronous communications, Greg Simeo, 
the future Ph.D,, worked on System 
Initialization and FileSystems {FAT, IFS, and 
theCDRQM filesystem). 

TEAM SPIRIT 

Successful completion of a project as large as 
OS/2 2.0 required a true team effort The OS/2 
team member does not work in a vacuum, A 
programmer who sits at his or her desk in 
solitude, coding and debugging, does not fit 
into this new world of software development. 
No one is simply a programmer. Everyone is 
touched by design, development, testing, and 
documentation activites within and outside his 
or her immediate development team. 

Because of the 
structure of the 
operating system's 
kernel components, 
Phil Doragh and his 
team spent much of 
their time working 
with testers. Kip 
Harris, staff 
programmer for 
MV DM and Device 
Drivers, estimates 
that at least half of 
his time was spent 
working with other OS/2 development teams. 
"Designing the specifications and developing 
the code for a component is only part of a 
developer's responsibility," explains Kip. 
"Testing is also a substantial part of the job, as 
is assisting Information Development with 
technical publications." 

Craig Bennett estimates that he spent as much 
as fifty percent of his time working with 
people from other development teams. 
"Because the changes for a particular build of 
the operating system or toolkit are brought 
together for the first time during installation, 
we have dependencies on all OS/2 teams, A 
large portion of the changes that are made to 
the system also require changes to installation: 
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laying out and placing system files on the 
user's hard disk, modifying an .INI file, or 
building a new CONFIG.SYS. Because the 
installation programs have a user interface, I 
also worked with the Usability, Common User 
Access (CUA), and Information Development 
teams. It was interesting to see how each 
group had a different view of how things 
should look and act/' 


TEAM COMMITMENT TO 
MARKET-DRIVEN QUALITY 


"If it doesn 't 
work on OEM 
equipment, 
then OS/2 is 
broken ." 

—Bill Bodin 


Toward the goal that OS/2 be the best PC 
operating system and the operating system of 
choice, all team members are keenly aware of 
customer needs. Throughout the development 
cycle, the OS/2 team responded to feedback 
from internal, usability , and external test 
groups made up of a variety of users. Thirty 
thousand beta copies of OS/2 ZO generated 
comments that helped shape the final product. 

Steve Glazer notes that market-driven quality 
initiatives are reflected in every facet of OS/2. 
"We are driven to provide the customer with a 
product that will be a useful tool in developing 
great applications and that will add value to 
his or her products. With its ease of use, data 

integrity, and 
robustness, OS/2 
provides a vision of 
computing for the 
nineties." 

Chris Andrew and 
the Workplace 
Shell™ team 
wanted the right 
solution for the 
new object-oriented 
user interface. 
"CUA 91 was the 
blueprint for the 
Workplace Shell/' says Chris. "However, we 
felt some freedom to bend the rules defined by 
CUA and to work with them to reach the right 
solution. The Boca Usability folks and the test 
facilities that they have were very instructive 
in trying to see which solutions worked and, 
more importantly, which were confusing to 
the test participants. The usability folks 



brought in many, many people to see if they 
could use OS/2, and our team was frequently 
in there watching them. We were usability- 
driven, so the Workplace Shell would be as 
usable as we could make it" 

Because of substantial investments in non-IBM 
hardware, customers demand open systems. 
This means that for OS/2 2.0 to be successful, 
it must run on most or all major Intel 386- 
compatible workstations. According to Bill 
Bodin, "We took the attitude that if it doesn't 
work on OEM equipment, then OS/2 is 
broken." To meet this challenge, the OS/2 

team, particularly 
those in the area of 
device support, 
found themselves 
working with 
hardware and 
software developers 
from other 
companies on a 
daily basis. 

Bill Bodin, for 
example, worked 
closely with 
software engineers 
across the country to integrate code 
supporting a variety of OEM video adapters. 
Bill and his team assisted them with creating 
Presentation Manager™ display drivers. Kip 
Harris and his team shared a similar 
experience: "Many of these developers have 
joined us on site in Boca Raton, and many 
more have assisted us by telephone or fax," 
says Kip. "A lot of us are on the phone with 
technical people from another company at 
least once a week, and for some of us, like 
myself, it's perhaps a daily thing. This contact 
has been very beneficial, as developers from 
other companies give us considerable insight 
into the marketplace/' 

Even when meeting the challenges of 
supporting DOS and Windows applications, 
customer requirements were top priority, Terri 
Beck emphasizes, "Our entire design point 
w'as compatibility, compatibility, 
compatibility. We attempted to run every 
Windows 3.0 standard mode application off 
the shelf," 
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Stuff Yourself 



All the programming you tan stand for about $2 an issue.* 



Computer Language serves up serious programming, 
not just a lot of industry hype and copious amounts 
of C or Forth code for do-it-yourself toy programs. 


Bur brace yourself for a deluge of information. 


Computer Language is not for beginners. It is, how¬ 
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THE OS/2 TEAM ON OS/2 2.0 

OS/2 team members view their product with 
pride and have great expectations for its 
reception in the PC community. Their views 
reflect a strong belief in OS/2's value and their 
deep commitment to market-driven quality. 


"Our entire 
design point was 
compatibility, 
compatibility, 
compatibility ." 

—Terri Beck 


Kip Harris believes that ''among other 
features, the OS/2 2.0 DOS environment is a 
terrific development environment even if the 
developer is initially targeting only DOS 
platforms. DOS applications under 
development or test will not hang the system; 
multiple executions of the DOS program can 
be run and debugged simultaneously; and of 
course, multitasking capability permits a 
developer to edit source, compile, and debug 
an application simultaneously/' 

The ability of Windows and PM applications 
to communicate through dynamic data 
exchange (DDE) makes it easier to migrate 
gradually to PM. Terri Beck points out that 
"customers can replace pieces of their 
application set without changing their entire 
environment. They can use PM front ends to 

launch existing 
DOS or Windows 
programs so they 
don't have to 
migrate all their 
code to PM at once. 
They can also start 
migrating some of 
their Windows 
code to PM, placing 
communication 
links with the new 
PM code into the 
remaining 
Windows code/' 



Steve Glazer adds, "The flat design of user and 
system memory is a major innovation for 
using the full power of the $0386 memory 
management capabilities. OS/2 is a unique 
product in the marketplace; it adds value and 
immense capability to any personal computer 
configuration. It has everything a customer 
wants in an operating system. It works with a 
wide applications base, providing the 
capability to develop powerful 32-bit 
applications. It is reliable, providing 


developers with a secure environment to 
create stable applications. And it is user- 
friendly." 


Chris Andrew says, "With the object methods 
we've published, the programmer is able to 
get right in there and start adding his own 
object classes to the Workplace Shell. 
Workplace objects benefit from all function 
defined for the workplace object class they are 
derived from. You don't have to worry about 
where your object is stored. You don't have to 

write any code to 

^ | support drag-drop 

or display an icon. 
This is all taken 
care of. All you 
need to do is sit 
down and write the 
object's new 
function. Also, by 
being object- 
oriented, your code 
will probably get a 
lot of side benefits 
like reuse and good 
modularity," 







Chris Aridmv 


"Another benefit of Workplace," continues 
Chris, "is that all of the shell's features can be 
customized or removed by writing 
replacement object classes that either add or 
subtract function from the shell, whatever is 
required. For example, a corporate account 
may have strong views about its employees 
playing with the games and other fun stuff in 
OS/2 2.0, With just a little programming, that 
customer can disable everything except the 
authorized programs and procedures on the 
operator's machine." 

Bill Bodin is particularly proud of the 
SuperVGA support now being introduced for 
OS/2 2.0: "This support gives PM display 
drivers written for many popular adapters the 
ability to set SuperVGA modes in protect 
mode, ft also provides vast support for 
SuperVGA DOS applications that formerly 
didn't execute properly on OS/2.1 am very 
pleased with the level of support we were able 
to attain for the general availabilitv level of 
OS/2." 
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THE LIFE OF AN OS/2 
DEVELOPMENT PROGRAMMER 

Because of economics and a rapidly changing 
marketplace, IBM, like other companies, must 
do more with fewer people in a shorter period 
of time. Given the size and complexity of 
OS/2, this means that the lives of OS/2 
development programmers are not easy. 

Early in the product development cycle, their 
work revolves around coding, testing, and 
entering the public build of the product. In 
comparison to later phases of the development 
cycle, the programmers work at a slower pace, 
focusing primarily on code. This is not 
necessarily an easy task. For example, because 
of the newness of the Workplace Shell and the 
demands placed on the small Workplace Shell 
team for demonstrations, the team had to be 
physically removed from OS/2 development 
for approximately four months to complete 
their code. 





Greg Sirtiffl 


After the code 
alters The public 
briiM,,tthe 

fptrogriimmers' days 
not olVe around 
problem 
determinations, 
fixes, testing the 
fixes, and making 
the next build. The 
demands on a 
programmer's time 
depend on the 
urgency or severity 
of the problem, the difficulty of the problem's 
solution, and the frequency of public builds. 
Problems come from internal and external 
testers, from usability, and from anyone using 
a prerelease driven Problems are classified by 
severity level based on the usability impact on 
the system or component and the availability 
of a workaround, A programmer's workload is 
prioritized according to the severity of 
problems reported against his or her 
component. Turnaround times for solutions 
are based on the severity of the problem, with 
more serious problems that impact the entire 
system requiring immediate attention. 


As the development cycle for OS/2 2.0 
progressed, the pressures on programmers, as 


well as on the rest of the team, became 
enormous. Days became longer, with dinners 
served nightly in a patio area of the building. 
Long days turned into long nights and 
weekends. Weekly dinner menus grew to 
Include weekend meals. 

A project of such scope and importance 
requires serious commitment from all 
concerned. From the time OS/2 2.0 was 
launched in the spring of 1991 to its release on 
March 31,1992, the OS/2 team worked large 
amounts of overtime—typically 60 to 70 hours 
per week. Some, like Bill Bod in and Greg 
Simco, worked 80 to 90 hours a week (twelve 
to fifteen hour days, seven days a week) in the 
last weeks of the development cycle, A sign on 
a Workplace Shell team office door, punning 
on the System Object Model (SOM) used to 
implement the shell, reflected the long hours 
of work. 



Some developers tried to reach a balance 
between work and home by creating 
individual work schedules with their 
managers. Kip Harris explains, "It wouldn't be 
unusual for me to take a few hours off midday 
to take my 3-year-old daughter to a library 
class. At another point, 1 might come in at nine 
at night and work several hours. Sometimes I 
would handle design work or correspondence 
from home after putting the kids to bed/' Greg 
Simco, who normally goes to the gym six days 
a week, went to the gym whenever he could 
get away, morning, afternoon, or evening. 

All members of the OS/2 team sacrificed some 
part of their personal lives to finish the project 
on schedule. They were unable to give normal 
attention to marriages, families, friends, 
hobbies, or special activities. Some were 
unable to juggle schedules and to spend 
quality time with their children. Some had to 



Twenty-four 
hours after 
Windows 3.1 
was released, 
os/2 2.0 ran a 
Windows 3.1 
application. 
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"OS/2? I've got 
my best people 
working on it!" 

—Shon Saliga 


place the pursuit of higher education 
temporarily on hold* Home maintenance 
became a very low priority. 

All OS/2 developers were and are committed 
to the project, one they really believe in. Kip 
Harris summed it up: "One thing I see, over 
and over, is a great deal of personal 
commitment from the development team. We 
believe in this product and want to see it win* 
The developers have given and are continuing 
to give everything they've got to make it 
happen/' This was most recently 
demonstrated at COMDEX/Spring in Chicago 
where, 24 hours after Windows 3,1 was 
released, 05/2 2.0 ran a Windows 3.1 
application. 

As for the future of OS/2, Terri Beck says, 
"OS/2 must he a success, it's a good product, 
long needed by the marketplace. 05/2 ls 
giving the PC the legitimacy found today in 
much larger systems. We have to reeducate 
programmers in the marketplace. They are 
used to programming any way they want 
under DOS—no rules. Can you imagine what 
would have happened if people writing apps 
for VM had that philosophy? OS/2 requires 
that level of discipline of programmers." 

IN RECOGNITION OF THE 
ENTIRE OS/2 TEAM 

The OS/2 development team is a unique 
group, "sharp and very creative," according to 
Craig Bennett, working in a "very challenging 
environment/' according to Kip Harris. 

But OS/2 development is only one part of the 
entire OS/2 team* Beside every developer is a 
planner, a system architect, a system tester, a 
performance specialist, a usability expert, an 
information developer, and a technical support 
person. And a strong management team (in 
fact, the entire corporation) stood behind the 
entire team, making it happen. 

This commitment from management was very 
important to the OS/2 2.0 development effort. 
Bill Bodin says, "You could see the 
commitment in everyone from first-line 
managers to top executives* I remember on 
several occasions taking the long walk back 
from the OEM test lab well past midnight, and 


Lee Reiswig (assistant general manager of 
programming for IBM Personal Systems) was 
still in problem tracking (PTR) meetings and 
still going strong. It is tills level of involvement 
that kept us motivated despite the grueling 
schedule." 

Another management team member involved 
in PTR meetings was Shon Saliga, OS/2 
Systems Development Manager, Saliga tells us 
that his favorite quote from those meetings 
was 'Tve got my best people working on it." 
Says Saliga, "The dedication to making OS/2 a 
versatile product that DOS, Windows, and 
OS/2 customers would love was amazing* 
Even though great personal sacrifices were 
made, I believe people will look back and 
agree that this was a high point in their 
careers," 

Former PS PC 
Director Tommy 
Steele, commenting 
on OS/2 2*0 and the 
OS/2 team says, 
"The development 
of OS/2 2*0 was 
truly a team effort. 
The men and 
women who 
developed this 
project took 
ownership and 
pride in their work 
and made quality their highest priority. It was 
the first time that we opened up our 
development process to the public and made 
our people widely available to talk with 
customers and with the press* 1 believe the 
OS/2 team learned a lot about who our 
customers are, what they want in our product, 
and the importance of quality because of this 
new process*" 

"OS/2 2*0 really is a product that was owned 
by the people, not by the management team," 
adds Steele. "Working with our customers, the 
team determined what functions should be in 
the product and when the product was ready 
to ship. This customer-driven development 
process enabled them to build a quality 
product with superior technology that delivers 
the function that our customers want, Tm 
extremely proud to have been a part of this 
exceptional team." 



Tommy Steele 
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Get your hands on over 30 new and incredible ways 
to use a computer at The Computer Museum 
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Unfortunately, this article cannot cover the individual stories of each of the hundreds of people who 
worked on the project. However , we can share with you a team photo that includes many of those 
individuals. In addition, the entire OS/2 team is recognized within the installed OS/2 2.0 product By 
clicking the mouse on the Desktop and then pressing SHFT-CTRLALT-o, you can view a bitmap image 
that scrolls the names of all of those who worked on the product 


Click on the 
Desktop; press 
Shift-CTRL- 
AlT-o 



Mary Wright, IBM Personal Systems LOB , WOO 
N.W. 51st $t. f Boca Raton , FIa. f 33429. Mrs * 

Wright is a staff information developer in Boca 
Raton . She came to IBM in 1982 as a developer of 
the Customer Support System , having previously 
worked as an applications programmer specializing 
in engineering applications. In 1985, she joined 
OS/2 development and was the original developer of 
the Monitor Dispatcher. In 1988, she joined 
information development, where she is the technical 
editor for the OS/2 Programming Library. She was 
the lead writer for the Application Design Guide 
and the three-volume Programming Guide in the 
OS/2 2.0 Technical Library. Mrs. Wright received a 
BA. in Mathematics and Russian and an MA. in 
Russian from Case Western Reserve University. 
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Software Tools 

Building Production-Quality 
Client/Server Applications 



Jim Henry 



Brent Wit Hat ns 


by }im Henry and Brent Williams 

S ince IBM introduced the IBM PC in 1981, 
transforming the microcomputer 
overnight from hobbyist's plaything into 
essential business tool, more and more 
business leaders have looked to integrate these 
machines into complex corporate computing 
networks. In time, companies made the 
machines an integral part of enterprise-wide 
network systems. However, despite these 
advances, the kinds of applications 
successfully implemented on networked 
systems haven't changed significantly. No 
matter how extensive the corporate 
networking vision, users are often willing to 
trust their networked microcomputers only 
with basic applications such as individual 
productivity packages, decision support, and 
electronic mail Meanwhile, cost pressures 
continue to influence the movement of the 
organization's critical applications from 
mainframe systems to network-based 
applications. 

The main barrier to adoption of client/server 
technology for production-quality applications 
is the concern that this environment cannot 
easily deliver the reliability of traditional 
mainframe computing. This concern arises 
primarily from software companies' lack of 
understanding as to just how much integrity 
and control is enough for true production 
applications. Another problem is the greater 
chance of failure in a client/server network. 
Instead of a relatively straightforward 
hardware path and one process to execute the 
application, a client/server application spans 
at least two machines and an enormous 
amount of system software: a user interface 
manager, a network manager, a database 


manager, and so on. The odds are that a 
client/server network will be less reliable due 
to the large number of components that could 
fail. 

Despite these problems, software technology 
has advanced significantly since the 
introduction of the first IBM PC. Because some 
programming environments (for example, 
OS/2) now support substantial amounts of 
memory and other capabilities, and because 
OS/2 and most database managers are now 
production-ready, it is possible to build 
programs that approach or exceed the 
requirements of production applications. With 
appropriate software unifying all components 
of the client/server environment and 
providing performance optimization and error 
recovery, production-quality applications can 
now be built on LAN-based systems. 

Building robust client/server applications 
requires some of the most advanced features 
of today's operating and database systems. For 
example, OS/2 provides multitasking, 
interprocess communications, shared memory 
management, and other key features necessary 
to support sophisticated client/server 
functions. Relational database management 
systems (RDBMS) for OS/2 have evolved to 
the point that data integrity, high throughput, 
and network efficient versions are the norm. 
This article discusses the requirements that 
must be met for the client/server applications 
to be successful in production use. The 
support offered by development tools 
available for this environment will also be 
compared to the full requirements of 
production applications. Ellipse™, a product 
available from Cooperative Solutions, will be 
described to illustrate a new development 
approach that meets these requirements. 
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REQUIREMENTS FROM THE 
DEVELOPER'S PERSPECTIVE 

The key requirements of quality client/server 
production applications are similar to those of 
mainframe applications. However, in a 
client/server environment, additional 
capabilities must be built into the system to 
handle problems unique to client/server 
computing. 

Integrity And Reliabililty 

Users insist on the same standards of 
application reliability and data integrity for 
client/server applications as they do for 
mainframe applications* From a business 
perspective, a production system is critical; 
since lengthy downtimes to isolate software 
bugs or data corruption problems are 
unacceptable, the system users must be able to 
trust the system implicitly, without extensive 
human oversight 

Mainframe programmers create production- 
quality applications with the help of a number 
of system software components that support 
recovery from various error conditions. But 
these applications, such as IBM's IMS™ and 
DB2™ databases and the CICS™ 
teleprocessing monitor, are either not 
available or not sufficiently well accepted in 
the microcomputer community. 

OS/2-based client/server development tools 
typically use only the limited recovery 
facilities in the database to recover from a 
failed in-progress transaction. Although the 
database typically rolls back the database 
component, programmers tend to rely on the 
RDBMS for all recovery functions* 
Unfortunately, the DBMS only insures that the 
database is returned to a consistent state after 
an aborted transaction, while network glitches 
and server faults can leave the client side of the 
application unstable. The client side of the 
application is thus left to the programmer to 
protect* 

The client/server programmer is responsible 
for writing some reasonably complex code to 
first anticipate all recoverable errors and then 
restore the client to its exact state prior to the 
error. The programmer must protect working 
storage tables, variables, and the user interface* 


Code must be written in C or in an arcane 
scripting language provided by the tool 
vendor* 

In a client/server environment, transaction 
management actually becomes more difficult 
than in a mainframe environment. First, to 
deliver mainframe like capacity, client/server 
applications may be installed in dozens or 
hundreds of sites, pushing data closer to the 
customer. Or multiple machines may be 
employed to give higher performance on a 
single LAN. In either case, reliable transactions 


Production Requirements C/S Attributes 



Figure 1: Requirements far client/server computing 

will need to span more than one server 
machine. Although the technology for reliable 
updates, principally using the two-phase 
commit protocol, has been in existence for a 
long time, it has typically been difficult to 
implement, even with support from the 
database manager* What is needed to make 
real robust applications span the entire 
enterprise, then, is a transaction system that 
can provide reliable distributed updates with a 
minimum of programmer effort. Without this 
capability, users will turn away from 
distributed client/server applications* 

Scalability 

Scalability is the ability of an application or 
computing platform to grow r to accommodate 
increasingly larger throughput. Client/server 
environments require more server power as 
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more clients are added* Server power can be 
expanded in three ways: you can replace small 
servers with larger ones, add processors to the 
multiprocessor server, or add more servers 
and redistribute the databases. As a result, it's 
important for client/server development 
environments to enhance the scalability of 
production quality applications without 
programmer difficulty . 


Menu 


r — 

Sales Management 

▼ 

* 

^ Customers Orders Window Edit Help 


Prospect Order 



Orders 



. Command; 
Transaction 



Figure 2: Graphic interface features supported in Ellipse 


Performance 


A client/server 
application 
demands 
integrity and 
control 


Production applications need to take full 
advantage of all the power offered by the 
clients and servers on a LAN. While there may 
be enough CPU cycles on the LAN to rival or 
exceed the available mainframe resources in a 
corporation, LAN computing power is 
distributed among a large number of small 
machines. Developers must therefore partition 
their client/server applications to run 
different parts of the application on the most 
appropriate machines. The primary goals of 
this distribution are the reduction of network 
traffic (a new problem for downsizing 
mainframe applications) and maximized use 
of available MIPS* In other words, if part of an 
application can run on the server platform 
containing the resource it uses (DBMs, 
communication, and so on), message traffic 
can be reduced and computation optimized* 


Adding to the complexity is the fact that, in 
most organizations, the relative size of clients 
and servers can vary widely. Optimization, 
especially if required on a site-by-site basis, 
can represent a costly, repeated effort for many 
programmers. 

Concurrency 

Many client/server applications take 
advantage of today's powerful client 
workstations by selecting sets of records from 
the DBMS for local client-based processing. A 
scheduling system for a university might load 
records for all available classes to the client 
workstation as working tables* The user can 
then browse the working tables at speeds 
hundreds of times faster than could be 
achieved when directly accessing the disk- 
resident DBMS's tables* 

Concurrency problems resul t if selected 
records are kept locked for the entire time they 
are used by one workstation. Most 
client/server databases operate this way, 
unless programmers enhance concurrency 
capabilities. The typical approach to solving 
concurrency problems is to try to reduce the 
amount of time a given record is locked. But if 
the records are not kept locked, updates can be 
made by other users, without the knowledge 
of the initial user. The result is hard-to-find 
data integrity problems. Developers who are 
aware of the problem have to resort to 
elaborate programming to prevent them, while 
programmers unaware of the risks can create 
applications that lose data and corrupt the 
database. 

Mainframe programmers have used the 
"optimistic locking" paradigm, which allows 
the programmer to control the locking state of 
items in the database by writing substantial 
amounts of code. This method, however, 
typically requires substantial expertise to 
implement correctly. 

It is important to understand what your 
underlying client/server database does, and 
more importantly, what you will have to do in 
your client/server development to get the 
required level of concurrent access despite the 
database's concurrency algorithms* 
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Security 

Client/server application development tools 
depend upon the intrinsic security features 
provided by the LAN and DBMS. Production 
applications typically demand a higher level of 
security that limits users to specific 
applications, transactions within applications, 
and data items on screen displays. A human 
resources application might limit the users to 
human resources personnel and high-level 
executives, confine lower level employees to 
specific transactions that don't affect pay level, 
and suppress the display fields for salary 
amount for certain groups of users. The 
programmer must either custom code every 
application or write significant centralized 
run-time code to manage site specific security 
tables and to limit access to the protected 
objects. 

Graphical User Interface 

Because of the tremendous amount of low-cost 
computing power available on each user's 
desktop, client/ server applications can use 
substantial computer power to make the user 
interface as easy to use as possible. 
Programming this interface at a low level 
requires complex and hard-to-maintain code 
written in C. The ''event loop" programming 
model has proven to be extremely difficult to 
learn and write reliable applications in. Most 
client/server development tools eliminate the 
need for this kind of hand-coding but do Little 
beyond automating the user interface and 
client-side application logic. 

Life Cycle Management 

When critical applications are moved to a 
client/server environment, users need tools to 
manage complex projects. As client/serv er 
applications become more mainstream and the 
number of users increases, more client/server 
applications are being developed by teams of 
programmers who can modify and create 
modules without the awareness of the project 
manager or other programmers. The quantity 
of objects also continues to grow to an 
unmanageable number and chaos can result. 

Client/server applications might also need to 
be deployed to multiple locations serving large 


numbers of users. The resulting number of 
problems can make it extremely difficult to 
keep a project on track and nearly impossible 
to ensure that all workstations at all sites have 
current versions of code. Some add-on version 
control tools are av ailable, but they cannot 
prevent a programmer from accidently or 
deliberately circumventing their controls. 




Replicated Applications 

Corporations with many LANs often have 
standard applications that are centrally 
developed and then deployed to all sites. The 
client/server environment poses extra 
problems for the programmer trying to create 
an application that will run at all target 
locations, as different sites can vary as to 
DBMS vendor, location of database tables, 
printer locations, printer types, the client 
operating system, and so on. For example, the 
development and test site for an order-entry 
application might have all printers 
concentrated on one printer server and all 
DBMS tables on another server, while an 
installation site might have invoice printers 
attached to each client workstation and the 
DBMS tables split over two servers in two 
separate databases. The application must then 
be customized for each installation site. 
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PRODUCTION APPLICATION 
REQUIREMENTS VS. TODAY'S 
DEVELOPMENT TOOLS 

The first generation of client/server 
development tools eliminated much of the 
coding previously necessary to create the 
graphical interface and simple database access 
parts of applications. Graphical user interface 
front-end tools obviate the need to use event- 
loop programming and hand-coded calls to 
graphical user interface toolbox functions. 


Development Environment 


Production System 



Figure 4: Application life cycle manage men t 



Application 




Ellipse 
Production 
System 




Client Recovery 
Set Oriented Transactions 
Application Partitioning 
Advanced Security 
Application Portability 




J 


Figure 5: Bllipse/PS software layer automatically provides robust client/server applications 


Nonvisual functionality, however, still 
requires programming, as shown in Figure 3. 

The main programming effort on client /server 
applications is spent writing database data 
manipulation language (DM L) statements and 
utilizing C or a scripting language to meet the 
production application requirements just 
discussed. 


ELLIPSE FOR PRODUCTION 
QUALITY CLIENT/SERVER 
APPLICATIONS 

Ellipse, an integrated development and 
production environment from Cooperative 
Solutions, allows programmers to create 
production quality client/server applications 
without the need to resort to C programming* 
While the developer concentrates on the 
business functions of the application, Ellipse 
worries about error recovery and other 
production application requirements that 
would otherwise demand that code be hand 
written. The only coding the developer does is 
specifying the business logic for an application 
using a template-driven procedure editor. 
Ellipse consists of a development environment 
production system and a life cycle 
management system. 

Ellipse Production System 

The production system consists of several 
system software components that live on all 
participating machines in the network. The 
Ellipse/PS system software performs low-level 
system interfaces and recovery from system 
failures, precluding the need for the 
programmer to write system level code, as 
shown in Figure 5, 

Multiple Ellipse server processes can be 
started to support symmetric multiprocessing. 
In addition, each server node has one monitor 
process, which provides process failure 
recovery and security management 

Features 

To guarantee reliability and control in the 
client/server environment, the Ellipse/PS 
production system provides: 
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• Application Recovery. All copies of 
Ellipse/PS cooperate for recovery from 
every detectable and recordable error a 
client/server application might encounter. 
Ellipse/PS manages and monitors the 
network connections, server processes, client 
processes, and each other so that errors are 
detected, and where possible recovered 
from, without any developer coding. 



Figure 6: Applications may be built ami then deployed to multiple configurations 


* Application Partitioning, Ellipse/PS 
automatically partitions applications to best 
use the clients and servers while minimizing 
network traffic. Tire Ellipse Development 
Environment (DE) does not require the 
programmer to view the application as 
multiple processes, so programmers don't 
need to understand the client/server model 
or learn network APIs or RPCs. In unique 
circumstances, a system administrator can 
override automatic partitioning for site- 
specific reasons. 

* Efficient Set Concurrency* The concurrency 
problem posed when a set of records is 
loaded into the client workstation for local 
processing is eliminated by the optimistic 
locking capability of Ellipse/PS, which will 
allow a user to manipulate records on the 
client without having to keep them locked 
on the DBMS. When the application 
attempts to update the DBMS with one or 
more changed record values, EUipse/PS will 
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inform the application if one of those records 
was updated on the DBMS while the user 
was modifying the record in client memory. 

Portability 

Ellipse/PS always presents the same logical 
environment to the Ellipse applications, no 
matter what the physical environment. Ellipse 
applications are w ritten once and deployed to 
any supported site configuration. At 
installation time, the application administrator 
maps logical resources (printers, DBMS tables, 
servers, and so on) to a site's physical 
resources. A simple visual utility is run to 
allow the administrator to create a list of 
resources that match the list of logical 
resources displayed by the Install utility. 
Applications are generated once and then 
deployed to all locations without any 
application changes, as shown in Figure 6. 


ELLIPSE/PS AND APPLICATION 
LIFE CYCLE MANAGEMENT 

Ellipse manages the life cycle of an application 
from the development of its first components 
(objects) through retirement. All objects 
(forms, applications, procedures, reports, 
configurations, and so on) are stored in the 
Ellipse repository. The Ellipse configuration 
management and version control system uses 
the repository to manage all phases of 
application life. 

ELLIPSE DEVELOPMENT 
ENVIRONMENT 

The multiuser Ellipse/DE incorporates all 
facilities needed to develop and deploy 
production quality client/server applications. 
Ellipse/DE runs on OS/2-based workstations 
and takes full advantage of OS/2 multitasking, 
interprocess communications, large memory 
model, and the power of the high-end 
workstations and servers for which it w^as 
designed. 

With Ellipse/DE's integrated visual editors, a 
programmer without any experience in 
client/ server technology can rapidly develop 
applications, without having to program in C 
or a scripting language. Even stored 
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procedures for the DBMS are generated by 
Ellipse and will automatically execute where 
they will be most efficient. 

With Ellipse/PS taking responsibility for 
critical system-level functions, a developer can 
focus on the business functions being 
automated. CASE tools from a variety of 
vendors can be used to design a database to 
support the application. The application 
analyst then determines the business 
transactions that will manipulate the DBMS, 
generate reports, and interact with the users. 

Each activity, a group of related business 
transactions, is implemented by specifying a 
set of forms, procedures, and reports, with the 
flow between them determined by commands 
from pull-down menus. In production use, 
commands are also chosen from the pull-down 
menus, which are created by the visual menu 
editor, as shown in Figure 7. 

Commands can call procedures, bring up 
dialogue boxes, and run reports. Direct 
control given the user by the visual interface 
(menu bars, pull-down menus, radio buttons, 
and so on) eliminates the need to program 


navigation logic. Menus and forms are created 
with their respective visual editors, without 
any programming necessary. 

Procedures are easily created through the use 
of Ellipse's template-driven procedure editor, 
A programmer specifies procedure logic and 
data manipulation by indicating the statement 
type and then filling in blanks in the template 
(usually the variable names being tested or 
manipulated). 

An application's overall structure is 
represented by a diagram of object 
relationships automatically created by Ellipse 
as the visual object editors create application 
objects, shown in Figure 8. 

The development process is thus reduced to 
creating menus of commands, defining the 
commands with the command editor, and 
creating the forms and procedures using their 
respective visual editors. All testing, version 
control, configuration management, remote 
installation, and application management are 
achieved by Ellipse's integrated life cycle 
management. 



FORMS 


ACTIVITY 



PROCEDURES 


PROC 

IF_THEN 

ELSE_; 

END PROC 



REPORTS 



TABLES 


Figure 7: Integrated visual editors for rapid development 


Ellipse DE takes 
full advantage of 
the power of the 
high-end 
zuorkstations and 
servers for which 
it was designed. 
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SUMMARY 

Ellipse brings several functions to the OS/2 
developer, among them rapid application 
development via visual editors, dynamic 
recovery from errors, integrated configuration 
management and version control, and parallel 
development and testing. Applications can be 
deployed without program change and are 
protected by advanced application, 
transaction, and field level security. 


FOR MORE INFORMATION 
ABOUT ELLIPSE 

For more information about Ellipse, contact 
Cooperative Solutions at 1-800-4-ELUPSE 
or 1-408-377-030(1 


jim Henry is the Director of Technical Marketing 
for Cooperative Solutions Inc. He has over 22 years 
experience in the MIS field, with emphasis on 
OLTP, client/server processing , and DBMSs. He 
received a BS. in computer engineering from Case 
Western Reserve University. 

Brent Williams is a technical marketing manager 
at Cooperative Solutions. He is responsible for 
market analysis and creating the company's 
technical marketing publications. Williams has 15 
years' experience in the software business, most of 
that as a developer of relational database engines 
and other system software. He joined Cooperative 
Solutions as its first applications engineer in 1990. 
He holds a BA. in English literature from the 
University of California at Berkeley. 
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Figure 8: Ellipse's visual object editors ami application overuiezv diagram 
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Sept. 14-18, 1992 


The Software Development 
conference plays an important 
role in h elping developers keep 

their competitive edge... 
a must attend event.” 



Ian McPhee 

President 

WATCOM Systems. Inc. 



Follow the Leaders... 
... to SD ’92—Fall! 

By now you've heard about Software 
Development Conferences. This year 
more than 5,000 of the leaders in the 
development field came to Software 
Development Spring — that’s 100% more 
than last year! 

Why were they there? To catch up on 
the latest trends in programming — from 
object-oriented programming in C++ to 
developing for Windows to managing the 
people aspects of the software develop¬ 
ment process, 

They came to meet others who under¬ 
stand the significance of their efforts and 
achievements. They came to find answers 
to their current programming dilemmas. 
They came to rub elbows with the leaders 
in the software field, and to be part of an 
event that continues to shape the future of 
the software field. 

It’s not too late to take your turn at talk¬ 
ing one-on-one with the best in the busi¬ 
ness. Software Development happens 
twice a year, and now's the time to plan to 
attend this fall. 

At Software Development Fall the 
speaker lineup will represent the best and 


the brightest — industry leaders like 
Gene Wang. P.J. Plauger. Charles Petzold, 
Steve Mellon Tom Plum. Richard Hale 
Shaw. Bruce Eckel. Larry Constantine, 
Andrew Shulman, and Tom Swan to name 
just a few, 

These aren't just great speakers, they 
are great teachers who can provide pro¬ 
gramming solutions you can take back to 
the office and put to use immediately. 

Come to Software Development Fall 
and you’ll leave full of new ideas, reener¬ 
gized and ready to take on your next big 
challenge. 

It all takes place the week of Sept. 
14-18,1992 at the World Trade Center 
in Boston. Mark your calendar now. 
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Pamela MUarotomto 


IBM offers a 
number of 
application 
development 
products for 
OS/2 2.0 


Software Tools 

Application Development 
Aids for OS/2 2.0 


by Pamela Mitarotondo 

A number of application development products are 
available for OS/2 2.0. The IBM C Developer's 
WorkSet/2 is an entire programming environment 
that incudes a C compiler. Presentation Manager 
debugger, configurable “shell" (the IBM 
WorkFrame/2), and the Developer's Toolkit for 
OS/2 2.0. The revised Toolkit has been improved 
but still includes the familiar necessities. 

DEVELOPER'S TOOLKIT 

he Toolkit contains the software tools 
JL needed to build and debug your OS/2 2,0 
applications, sample programs to show you 
how to make use of the Application 
Programming Interface (API), and on-line 
information* 

TOOLS 

The Toolkit's array of tools is made up of build 
tools, Presentation Manager (PM) tools, 
libraries, and system debug support. Header 
files provide data types, data structures, and 
other OS/2 function definitions used during 
program compilation. C language header files 
have the .H extension. Figure 1 shows the 
Toolkit contents. 

Build Toots (utilities used to build programs) 

* EXEHDR enables a developer to display or 
change fields in the header of an .EXE file. 

* FWDSTAMP is used to add entry points to a 
dynamic link library (DLL) file. 


* XMPLIB creates an import library that resolves 
an application's external references to 
subroutines or procedures in DLLs. 

* LINK is used to build 16-bit .EXE files. 

* LINK386 is used to build 32-bit .EXE files. 

* MARKEXE is used to mark executable files as 
window-compatible and able to handle long 
file names. 

* MKHSGF creates a binary message file from 
error, help, prompt, or general text 
information* 

* HSGBIWD binds a message file to an 
application's executable file* 

* NMAKE automates the process of building 
applications. 

* PACK compresses one or more files into a 
single file, optimizing disk space and I/O 
performance for application installation. 

PM Tools (utilities used to build a PM 

interface) 

* Dialog Editor (DLGEDIT) creates and modifies 
dialogue boxes. 

* Font Editor (FONTEDIT) creates and modifies 
fonts* 

* Icon Editor (KONEDIT) creates and modifies 
icons and bit maps, 

* IFF Compiler (XPFC) creates a binary image of 
on-line help information for applications or 
on-line documents. 
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Resource Compiler (RC) creates a binary file 
containing PM resources (icons, menus, help 
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tables, and string tables) that can be 
appended to an .EXE or DLL file. 

• SOM Compiler (SC) creates header files, 
implementation templates, and a class 
definition file for the System Object Model 
(SOM) programming environment 

• Workplace Class List lists Workplace SOM 
classes and enables updating of the library. 

Libraries (used as input to the Linker that 

resolves an application's external references) 

* OS2286.LIB resolves application references 
to 16-bit OS/2 functions. 

* OS2386.LIB resolves application references 
to 32-bit OS/2 functions. 

System Debug Support 


Presentation-Manager based programs. 
Samples in each category (IMAGE for PM and 
WORMS for non-PM) illustrate porting and 
migration to the new 32-bit environment 

Included in the PM samples is a template 
sample that demonstrates the structure 
common to all PM applications. Another 
sample implements the new PM window 
controls (Container, Notebook, Slider, Spin 
Button, and Value Set) and demonstrates how 
a PM application conforms to Common User 
Access requirements. 

Other samples demonstrate window creation 
and manipulation, direct manipulation, drag 
and drop, retained graphics and 
transformation functions. A printer sample 
illustrates how to display and print text, 
graphics, metafiles, and bit maps. 



The system debug support environment is 
new in the Developer's Toolkit for OS/2 2.0 
and includes the debug kernel, symbol files, a 
debug version of the Presentation Manager, 
and tools that support debugging efforts. 

* MAPSYM is used to generate binary hies 
that the debug kernel uses to associate a 
symbolic name with an address in memory. 

* T is a terminal emulator used by the debug 
kernel to communicate with the system 
being debugged. 

A full-function Presentation Manager 
debugger is available in IBM's C Set/2 
Version 1.0. 

SAMPLE PROGRAMS 

Sample programs are working examples that 
demonstrate features of the operating system. 
Some of the familiar 16-bit samples have been 
rewritten for the 32-hit environment, and 
many new samples have been written to 
illustrate new functions, such as improved PM 
window controls and object creation and 
manipulation. Once installed, the sample 
programs appear in the Samples Folder and 
can be started from the Desktop or from the 
command prompt 

The sample programs can be classified as 
either Presentation Manager or non- 
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Figure I; Contents of the Developer’*, Toolkit 


There are also object-oriented programming 
samples showing the SOM and Workplace 
programming environments. ANIMALS and TP are 
SOM samples showing subclassing, 
inheritance, polymorphism, and public and 
private methods. WPCAR demonstrates how to 
create a Workplace object. 

In the non-PM category are memory 
management and dynamic linking samples as 
well as samples showing the use of threads, 
pipes, queues, extended attributes, and 
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semaphores. A set of REXX samples are also 
included to illustrate calling REXX from a PM 
application, use of the REXX subcommand 
handler and variable pool, and how a C 
application calls a REXX macro. 

Getting Started , in the Developer's Toolkit for 
OS/2 2.0, includes a description of each 
sample program. The Application Design Guide , 
included in the OS/2 2*0 Technical Library and 
also available separately, contains a matrix 
showing the function calls used in each sample 
program. 



Figure 2; On-line information for the Developer's Toolkit 


ON-LINE INFORMATION 

The on-line information included with the 
Toolkit was created using OS/2's Information 
Presentation Facility and uses hypertext 
linking, searching, indexing, and cutting and 
pasting to the system clipboard. To better meet 
programmer needs, the Information 
Development team has redesigned the on-line 
information as a multiple-window 
presentation, as shown in Figure 1. Six 
documents cover the information needed to 
develop an OS/2 application: 

• The Control Program Reference describes 
each base operating-system function 
indicated by the Dos prefix, 

* The Presentation Manager Reference 
describes each of the PM functions Dev 


(device), Drg (drag and drop), Ddf (dynamic 
data format), Gpi (graphics), Prf (profile), Spl 
(spooler), and Win (window). The PM 
Reference also describes graphics orders, 
application hooks, PM messages, and the 
new workplace methods. 

The Control Program and Presentation 
Manager references include input and output 
parameters, data structures, data types, return 
codes, and example code for their respective 
functions. 

* The Information Presentation Facility 
Reference contains guidance and reference 
information for the design and development 
of on-line documents and application help 
facilities. 

* The REXX Reference gives information on 
REXX functions, including call syntax, 
parameters, return values, and error 
messages, 

* The System Object Model Reference 
provides information for each of the classes 
and methods in the SOM programming 
environment as well as SOM C language 
bindings, the Object Interface Definition 
Language syntax, and the SOM compiler 
command syntax. 

* The Tools Reference describes each of the 
tools in the Toolkit, including system debug 
support. 

KwikINF, a new Toolkit utility, allows hot-key 
access to on-line information, either from 
within an editor or from the command line. 
Once started, this utility sets off an automatic 
search for the text string of your choice. KwikINF 
is configurable, enabling you to specif)' the 
default hot-key sequence, default book to 
search, and whether or not to bypass the pop¬ 
up Search window; it also works in any of the 
OS/2 session types (full screen, AVIO 
window, and PM window), If your application 
is running in a full-screen session or in an 
active PM window with a multiline entry 
(MLE) field, KwikINF retrieves the word over the 
cursor and automatically places it in the entry 
field of the Search window. For non-MLE PM 
and AVIO windows, however, you must enter 
the string manually. 
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TECHNICAL LIBRARY 

The OS/2 2*0 Technical Library has been 
revamped and improved as a result of 
customer feedback and competitive research. It 
includes familiar OS/2 programming 
information, with increased depth, breadth, 
and usability . The entire Technical Library is 
available in one package, or each book can be 
purchased individually as needed. An order 
form is included in the Toolkit package, or you 
can call 1-800-IBM-PCTB to order. 

Each on-line Toolkit Reference (except the 
Tools Reference) is duplicated in the Technical 
Library, which contains the following volumes: 

* Control Program Programming Reference 

* Presentation Manager Programming Reference, 
Volumes 1-3 

* Information Presentation Facility Guide and 
Reference 

* System Object Model Guide and Reference 

* Procedures Language 2/REXX Programming 
Reference 

Additional books in the Technical Library 
include guidance for the OS/2 2.0 
programming environment, device-driver 
information, and CUA information. 



GUIDANCE LIBRARY 

* The Application Design Guide provides an 
overview of OS/2 programming concepts, 
building dynamic link libraries, migration 
concepts, and information on using the 
System Object Model and Workplace 
programming environment. This book is a 
must for any OS/2 programmer. 

* The Programming Guide , Volume 1 provides 
in-depth information and code examples 
that will enable you to begin writing code 
using the Dos APIs. It includes sections on 
memory management, file systems and file 
management, program execution control, 
interprocess communication, exception 
management, and other base operating- 
system functions. 

* The Programming Guide , Volume 2 contains 
code examples describing the PM 
windowing functions. It includes 
information about window management, 
window controls, menus, dialogue 
windows, hooks, dynamic data exchange, 
direct manipulation, and other windowing 
functions. 

* The Programming Guide , Volume 3 consists of 
in-depth guidance and code examples 
describing graphics, printing, and device 
support in PM, It covers presentation space, 
graphics primitives, bit maps, retained 
graphics, metafiles, transformations, and 
other graphics functions. It also includes 
information on the print subsystem and 
spooling. 

* The Procedures Language 2/REXX User's Guide 
describes the REXX language, covering basic 
and advanced topics for the REXX 
programmer. It includes descriptions of 
variables, expressions, commands, 
arithmetic, and other REXX functions. 


DEVICE DRIVER LIBRARY 

• The Physical Device Driver Reference covers 
the architecture and operation of physical 
device drivers. It includes information about 
character device monitors, OS/2 physical 
device drivers, DevHJp routines, and I/O 
control (IoctL) functions. 
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* The Virtual Device' Driver Reference contains 
Liiformaiij .011 meeded to write virtual device 
drivers, including, virtual DevHlp functions 
and a d'esirriptidn of each OS/2 virtual 
device driver* 

* The Presentation Driver Reference describes 
OS/2 presentation drivers, ft explains the 
internal interfaces between PM and the 
driver and between the driver and the I/O 
subsystem. 

SYSTEMS APPLICATION 
ARCHITECTURE 

* The Systems Application Architecture: Common 
User Access Guide to User Interface Design 
explains the principles, components, and 
techniques of user interface design and how 
to design a product with a CUA interface. 


* The Systems Application Architecture: Common 
User Access Advanced Interface Design 
Reference lists all fundamental and 
recommended guidelines for designing and 
developing a product with a CUA interface. 
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TV 

Announcing TUB 5.0! 

Version Control for DOS & OS/2 

* The experts loved TLIB 4: 

J \,. amazingly fast... TUB is a great system,” PC Tech Journal 

“TUB has features and power to spare... TUB is easy to use and 
the fastest of the reviewed packages. 11 Computer Language 

"/ wilt not program without it," Uptime Magazine 

* Now TUB 5.0 adds: 

Autom atic bra nch i ng, Autom ati c version label i ng ac ross b ranc h es, 
Language-independent preprocessor, for 'conditional compilation 1 ' in 
languages which do not support it (like dBase). N-way-free version 
numbers. Branch and whole-library locking, OS/2 support. 

* Plus the features they loved in TUB 4: 

Check-in/out locking. Branching, for parallel development Keywords, 
Full binary file support (does not depend upon CRs in the file like other 
products). Wildcard and list-of-file support: can create lists by scanning 
source code for includes. Can merge (reconcile) multiple simultaneous 
changes and undo intermediate revisions. Network and WORM optical 
d isk s u ppo rt. Mai nf ram e -com patible do I ta generate r To r Pa n sop hie r 
ADR, IBM, Sperry formats. Includes integrated PD MAKE by L. Dyer; 
also integrates with Opus w MAKE, Slick 1 '' MAKE, others. 

MS DOS $139, OS/2 (with MS-DOS) $195 + shipping, 

5 station network: MS-DOS $419, OS/2 $595, Call for other sizes. 



Burton Systems Software 


PO Bo* 4156. Cary, NC £7519 (919) 233-8128 


World's most powerful tools for OS/2 ® 

Hamilton C shell™ 


The superior alternative to the 
standard OS/2 command proc¬ 
essor* Faithfully recreates and 
updates the entire UNIX® C shell 
language. Created explicitly for 
OS/2 using modern incremental 
compiler technology. Not one 
line ported from or created on 
anything but OS/2. Very liigh 
performance. Extensive support 
for multi-threading. 

Features: Full-screen command 
line editing * Filename and com¬ 
mand completion * History * 
Arrow and function keys * 
Unlimited size command lines * 
Recursive filename wildcard ing 

• Fully nestable control struc¬ 
tures * Command substitution 

* Aliases and shell procedures * 
PATH hashing * Background 
threads and processes. 


Over 130 commands: alias, 
cat,chirtod,c].s # cp,euc,dj ff, 
6 ir s, ds kr ead, ds kwr i t e, du, 
evaljr f grep,grep, hashstat, 
head, hi story, 1 abel, Is, ki 11, 
markexe, more, mv, popd, 
print f,ps,pushd, pwd, rm, sed, 
sleep, split, strings, tabs, 
tail* ter, tee, time, touch, 
tr, uniq, vol, wait, wc, 
where i s, xri and others. 

Meticulously adheres to OS/2 
conventions. Supports HPF5, 
long filenames and all networks 
under OS/2 1.2 or later and 32- 
bit and VDM applications under 
OS/2 2,0. 

$350.00. Unconditional 

satisfaction guarantee. 

($365 in Canada, $395 elsewhere,) 


Hamilton Laboratories 

13 Old Farm Road, Wayland, MA 01778-3117 
Phone 508-358-5715 • FAX 508-358-1113 
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Software Tools 

The Enhanced Editor 



Brian Proffit 


by Brian Proffit 

N o additional charge/' When's the last 
time you heard those words from an 
IBMer? On the other hand, how many times 
have you heard or read that there are no 
development tools available for OS/2? What's 
the likelihood, then, of there being a good 
development tool available from IBM at no 
additional charge? 

Okay, okay, this column has said before that 
editors are not something you bring up in 
polite conversation. There are developers out 
there who are so devoted (even fanatical?) 
about their favorite editor that no other 
product has a chance of being considered. 
Such is life. 


"No additional For those willin § to look at other P roducts ' 

„ though, the new Enhanced Editor (EPM) for 
CnClT^C. 05/2 2,0 is well worth a review. One of the 
strongest benefits, of course, is the price. It's 
exactly nothing, as EPM is included with OS/2 
2,0, When you install OS/2 2,0, the Enhanced 
Editor is offered as an option under the "Tools 
and Games" selection. It takes nearly 90OK of 
disk space, and end users probably won't 
install it (although perhaps they should). 

Every developer, however, should strongly 
consider doing so. 

Let's establish one thing up front. EPM is 
an "EDLIN replacement." That's what the 
system editor is for. EPM represents the fifth 
generation of an editor from IBM's Thomas J 
Watson Research Center in Yorktown Heights, 
NY. These editors have been used inside IBM 
for a number of years, and that experience 
shows. 

There are many features you would expect 
from a developer's editor. For instance, EPM 


includes syntax assistance. If the extension of a 
file is .C, EPM assumes that the file is a C 
program and offers appropriate assistance. If 
the user types if and presses the space bar, 
EPM fills in the conditional block: 

if 0 { 

} else { 

} /* endif */ 

Unlike many editors, however, EPM provides 
assistance for more than C programs. Help is 
available for Pascal and REXX programs as 
well. The same if statement for a Pascal 
program (extension .PAS) expands as: 

if then begin 

end else begin 

end; {endif} 

The if statement for a REXX program 
(extension <CMD) expands into: 

if then 

else 

Other popular features such as cut and paste 
are also supported. Of course, since EPM is a 
PM program, its cut and paste isn't restricted 
to its own windows. EPM uses the OS/2 
Clipboard to copy to and from other OS/2 
programs such as spreadsheets, word 
processors, and host sessions. 

Marking can be done in three ways. In line 
mode, complete lines are marked. In character 
mode, marking is linear. For example, if you 
start a character mode mark with the word 
"linear" in the previous sentence and end it 
here, the mark would follow around the line 
breaks to include only the words between the 
two marks. In block mode, the marked area is 
a rectangular region not necessarily related to 
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any word, sentence, or line boundary. Areas 
marked in block mode can then be copied, cut, 
moved, printed, and so on, regardless of 
geometry. 

As a PM editor, EPM allows the user to take 
advantage of graphical user interface features 
such as the Adobe Type Manager, and 
supports all installed fonts. It supports 
multiple colors and attributes such as bold, 
italic, underline, and strikethrough, 

Developers seldom request these features in an 
editor, thinking of them more as word¬ 
processing functions. But a developer can 
greatly increase productivity through their 
judicious use. For example, when you are 
paging through a program on the screen, 
having procedure and function declarations in 
a different color can quickly draw the eye to 
important parts of the program. Function calls, 
for example, could be done in a highlight color 
and comments in italics, making it much easier 
for a developer to locate the desired section of 
the program. Developers with an attitude will 
no doubt discover that comments they're 
forced to add to code can be done in fonts so 
small as to be unreadable: 

mainO // Kjf bass insists I vrite these dumb 

int stuff; // cQwients all vte r the place, but that 

char next; // doesn’t aiean I hate to like it 

Another way to move quickly to key sections 
of a program is through the use of bookmarks* 
The user can place bookmarks as needed 
through a file and assign them names to make 
them easier to negotiate in the future, Those 
with 400 lines of function code before the main 
program starts will appreciate the ability to 
move quickly to a bookmark at the beginning 
of main* 


One of the best features of EPM is its support 
of macros, which are written in REXX. It 
would be difficult to imagine a richer language 
available to a programmer's editor. Through a 
simple interface, REXX programs can parse 
text directly from the editor, manipulate it, and 
pass it back. This fits directly into IBM's 
positioning of REXX as the SAA Procedures 
Language. I encourage all application 
developers to consider using REXX as the 
extension language for their product. 

There are many other features that EPM has to 
offer, such as interfacing with the WorkFrame, 
drag-and-drop with the Workplace Shell, math 
functions, and draw mode. While I can't detail 
all of EPM's features here, 1 hope I have 
planted enough seeds of interest to encourage 
developers to study the online help included 
with the enhanced editor. This may be the 
greatest editor you didn't pay for. 

Happy developing! 

Brian Proffit, IBM Entry Systems Division, 1000 
NW 51 $t St., Boca Raton Fla. f 35429 , Proffit is a 
senior programmer in OS/2 software developer 
strategy. He is currently responsible for OS/2 
developer tools . He joined the IBM development 
laboratory in Boca Raton in 1983 , after Ivor king as 
a systems engineer with IBM Dallas * 
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Software Tools 

IBM Snapdump/2: Capture 
File for Problem Determination 



by Michael Garrison ami Cecil IV. Rogers, Sr. 

IBM SnapDitmpf2 TU is a set of tools that assists 
with problem determination far OS/2 systems , 
capturing a wide variety of system data into a 
single , easily transportable file. The collection of 
data is controlled by a tailorable flat ASCII file. 
Although a sample version of this file is shipped 
with SmpDump (SNAPDUMP.DAT), the file can 
be easily modified to customize data collection. In 
addition, SmpDump provides an easy-to-use menu 
interface for displaying collected system data. 


Michael Garrison Da ta Co llecti o n 

S napDump includes a program 
(SNAPDUMP.EXE) that allows the 
collection of several types of data; 

* Files (binary and ASCII) 

* Data areas contained in named shared 
segments 

* Standard output and standard error from 
programs invoked by SnapDump 

* Environmental information automatically 
collected by the SnapDump data collection 
program. 

* A system trace buffer (if the system trace is 
active). 



Cecil W. Rogers, Sr. 


* Hexadecimal plus ASCII 

* Hexadecimal plus EBCDIC 

* ASCII only. 

You can use the SnapDump formatter to 
extract data from the output file, returning it to 
its original binary format This is particularly 
useful for binary files that can only be viewed 
using specialized tools or programs (tor 
example, the Communications Manager 
configuration file). You can also extract 
executable files and use them to reproduce the 
problem on a support system. 

Operating Environment 

There are no special requirements for 
SnapDump other than the use of OS/2. 
SnapDump will operate in the following 
environments: 

* SE 1.2 through OS/2 2.0 

* EE 1.2 through EE 130.2 

* SE 1.30.1 (including Extended Services) 

* LAN Server 2.0 


HOW DOES SN APDUMP WORK? 


Formatting Data 

SnapDump includes a program 
(5NAPDF.EXE) that provides a PM interface 
for viewing and formatting collected data. 

SNAFDF.EXE provides three views of the data 
that can be selected by toggling the PF12 key: 


SnapDump consists of a data collector and 
format utility. 

IBM SnapDump/2 Data Collector 

The SnapDump data collection program 
(SNAPDUMP.EXE) utilizes a flat ASCII file as 
input. This file contains the instructions that 
specify what data is to be collected (for 
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* OS/2 information 


f/sqldbdir 

f/config.* 


f/sqlsystm 

f/syslevel.* 


f/sqldbcon 

f/startup.end 


f/sqluif.* 

f/*,ini 


f/sqlnodir 

f/os2Q001.dat 


f/sqlgudir 

f Aog0001.dat 


f/sqlogctl.lfh 

* 


f/dbdrqlib.cfg 

* FFST/2 files 


* 

* 


* LAN Server 2.0 

f/epw.ini 


* 

f/snapdump.dat 


f/net. err 

fZos2mlog.dat 


f/net.acc 

p/dir c:\os2\system\*.dmp 
* 


f/net.aud 

* Communication Manager 


* LAN status command 

p/display.exe 


♦ 

*p/net statistics requester 

f/*.cfg 


*p/net statistics server 

f/*,ndf 


*p/net config requester 

f/*.sec 


*p/net config server 

f/*.cf2 


*p/net files 

f/error.dat 


*p/net sessions 

f/message. <Jat 


*p/net share 

f/esinst.hst 


*p/net status 

f/acs.pro 


*p/net view 

*f/acslan.log 


♦p/net who 

f/lantran*log 


* 

f/c2instal.log 


* Workstation Status Programs 

f/install.log 


* 

f/message.log 


*p/netse$$2.exe 

f/custbld.hst 


*p/ncbstat.exe * 

f/cmfeater.dat 


*p/dirstat.exe 

m/\sharemem\acs\ras_seg 


p/findseg -S C:\ 

# 


p/qmc.exe -d 

* Database Manager 

* 


p/pstat.exe 


Figure 1: SNAPDUMP.DATfik 


example, files and memory areas) and which 
data gathering programs are to be invoked. 
The flat file approach makes data collection 
with SnapDump very flexible because it makes 
it easy to add or remove items to be collected. 
When run, SnapDump will produce a single 
output file that contains all collected data. 

SnapDump is invoked from the command line 
through one of three forms of the command; 

* SNAPDUMP— This command assumes that the 
input file, snapdump.dat, exists, and that it 


contains a list of files, data, and programs to 
be processed. The output file defaults to 
snapdump.dmp. 

* SNAPDUMP {input-fname}— The {input-fname} 
parameter is the name of the flat ASCII file 
containing the list of items to be captured. 
The output file defaults to snapdump.dmp. 

• SNAPDUMP {input-fname dump-fname}— The 
{input-fname} parameter is the name of the 
flat ASCII file containing the list of items to 
be captured. The {dump-f name} parameter is 
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the file into which SnapDump will write all 
the captured data- In this document, it is also 
called the SnapDump output file. 

The SnapDump Inputt File 

The SnapDump input file controls the 
information to be captured in the output file. It 
may be edited with any ASCII editor, 
including the OS/2 system editor. The types of 
information that can be captured {and how 
that information is specified in the flat file) are 
listed below. 


Ffle name: 


Open 


SNAPDUMPUMP 


Directoiy is: C:\ 


Files: 


Directories: 


SNAPDUMP, DM P 

f 


3 0 



Open | 

Cancel 



BIL 


CFG 


CMG 


CMHB 


COMPORT 

— 

CONSOLE 

. 

DF 

■ 

DiSKSNAP 


DOC 


ELG 


EPM 


EFV 


EPVTOOL 

T 

□ n 



ydpj 


Figutv 2: File-open dialogue 


File Options Help 


Dump Formatter 


SNAPDUMP.DMP 


Izhi 



COMSPFOC: \ OS? \ CMO. EXE 

PATH=Cl\0S2;C:\MUGLIB:C:\CW_ IB;C:\lBMLAmNETPROG; C.\OB2\ SYSTEM; C; U)S2 W NSTA1 
DPATH=C: \0S2;C:\MUGL I B\DLL;C;\CMLJB;C:WBMLAN\NETPROG; C:\052\SYSTEM; C;\052\ 
PROMPT-SifSpl 

INCLUDE=C:\1BKC2\IWCLUDE;C:U00LKT13\CVIWCLUDE;C:\T0QLKT13 1 HMDM\IUCLUDE; 
TMP=C;WBMC2\TMP 

LIB-C: \ I 8ML2\LJ B; C: \0S2;C: \ 1BMC2\B!N;C; \OS2VSYSTEM;C:\0S2\ I MSTALL:t: \: C: \T0< 
HELP=C:V0S2\HELP:C:\T00LKT13\DM;C:\T00LKT13\DTL;C:\T001KT13\BIM: 

KEYS-ON 

BOOKSHELF=C:\OS2\BOOK;C:\TOOIKT13\PRQGREF; 

PfiOGREF=PRimm INF*PRCPJNF+PRGPIFN. INF*PRWINFM. INFfPRDATA.INF 
IPFC=C:\T00LKT13\IPFC; 

C:\0S2\SYSTEMS SNAPDUMP. DIE 
snapdump 


Figure 3: Maximized firsi window of SnapDttmp/2 


* An f/ in column 1 indicates that a file is to be 
captured, as in f/config.sys. When a file is 
captured, the contents of that file are 
appended to the Snap Dump output file. 
Wildcards may be specified, but be aware 
that the SnapDump output file may become 
very large if the wildcard specification is too 
broad. Any files in use, such as the 
Communications Manager MESSAGE.DAT and 
ERROR * DAT files, are collected. 

* An p/ in column 1 indicates that the 
specified program is to be invoked, as in 
p/c:\qmc.exe -d. You can specify any 
programs (including CMD files) that can be 
run from the OS/2 command prompt and 
write to standard output or error. The 
output of the program is appended to the 
Snap Dump output file. Output from 
programs that use other techniques of 
writing to the screen, such as Presentation 
Manager Win or VIO calls, cannot be captured 
by SnapDump. 

* An m/ in column i indicates that a named 
shared memory segment (\SHAREMEM\..,) is to 
be captured, as in hi/\SHAREMEM\ACS\RAS_SEG. 

The contents of the segment are appended to 
the Snap Dump output file. Wildcards for 
named shared memory are not allowed, and 
certain segments are protected and cannot 
be dumped. You can obtain the names of the 
named shared memory files in the system by 
issuing the command pstat /m at the 
command prompt. 

* Any other value in column 1 causes the line 
to be treated as a comment. 

If the system trace is active, the system trace 
buffer is automatically captured by 
SnapDump and appended to theSnapDump 
output file. 

Searching for Files 

When Snap Dump scans for files, it will search 
all accessible drives, including shared drives 
on servers and disk drives. If multiple 
instances of a file exist, all will be collected. 

Sample SnapDutnp Input File 

The input file SNAPDUMP.DAT, shown in 
Figure 1, is included with the SnapDump/2 
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package. It can be modified as required with 
your editor. 

The SnapDump Format Utility: 

The format utility provides a simple menu 
interface to select and display the contents of 
the SnapDump output file. Because each data 
item collected in the dump file is tagged with 
an entry title, it is easy to select a specific data 
item for display without displaying the entire 
dump file. 

The format utility can also be used to extract a 
specified data item and return it to its original 
binary format. The file can then be extracted 
from the dump file and stored individually, 
(This is particularly useful for binary files that 
require specialized formatters.) 

You can access the format utility directly from 
the command line by entering SNAPDF {dump- 
f name}. The {dump-f name} parameter is the name 
of the file containing data previously captured 
by SnapDump. 


If the {dump-f name) parameter is supplied, or 
snapdump.dmp exists, the "'Dump Formatter" 
window will be displayed. 

If no dump file name is specified and a file 
named snapdump.dmp doesn't exist, the 
standard file-open dialogue box will appear to 
assist the user in selecting a dump file name, 
and the file-open dialogue will appear as 
noted in the Open window, as shown in 
Figure 2, 

You can use either the mouse or the Tab and 
Shift keys to move between controls in the 
dialogue box. To move between the Open, 
Cancel, and Help buttons, use the left and 
right arrow keys. A user can press the FI key 
or click on the Help button to obtain context- 
sensitive help on a selected control. The 
"Directory is:" field is read-only and allows 
the user to see long subdirectory names. 

Only files identified as SnapDump or First 
Failure Support Technology/2 (FFST/2) will 
appear in the Files: listbox. The user may enter 



It is easy to 
select a specific 
data item for 
display without 
displaying the 
entire dump file. 



Let Gpf write the GUI you design 

Using the powerful point and click visual programming environment of Gpf 4 , you can prototype, test 
and generate a complete OS/2 PM GUI in a few hours or days rather than the weeks or months 
required to hand code the same design. Even a relatively simple GUI can require writing thousands 
lines of code, but with Gpf you simply draw your user interface on the screen. The integrated 
editor of Gpf permits actions and context sensitive help to be linked to controls as you 
Gpf then generates error free ANSI C complete with embedded SQL statements. 

to take full advantage of OS/2 PM, the most powerful and robust GUI system 
Gpf code directly accesses the PM API, there is no run time module to distribute 
with your application and no added overhead or royalties. 

Gpf keeps the entire design definition in one file. This permits easy re-entry for updates as well as 
regeneration for different targets 32 bit OS/2 and 16 bit OS/2 code generation. 




Gpf 


SYSTEMS, INC. 


Gpf supports^ 

Simple and direct linkage of the 
interface to program logic, built in or 
user defined functions 

Direct association of help screens with 
controls, and complete integration into 
the PM Help Presentation Facility. 

Flexible use of Presentation objects 
[fonts, colors, etc.) with controls and 
windows (client area and frame). 


iS out 


Simple inclusion of bitmaps for use on 
About screens, user-defined buttons, and 
menu or pulldown entries. 

Automatic embedded SQL statements to 
read OS/2 DataBase Manager tables, 
directly into combo or list boxes. 

Multi-thread programming. 

Multiple source file generation. 

Automatic creation of controls that scale 
with window size. 

Inclusion of user defined controls 


Order Gpf today for just $995, 

Call Gpf Systems Inc. at: 

(203) 873-3300 or (800) 831-0017 - fax (203) 873-3302. Free demo software available 
P O. Box 414 f 30 Falls Rd., Moodus, CT 06469 

* GUi Programming Facility 
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File Options Help 


Dump Formatter 


SNAPDUMP.DMP 


\zh 


IBM SnapDump/2 Section t 


3 


05-06-1992 


11122:02.28 


SnapDump 


Process Environmen 


Process Environment 


C:\CONFiG.OOO 

C:\CONFfG.BIL 

C:\IBMLANVNETSRC\HVCONFIG.H 

C:\CONFIG.SYS 

C:\0S2\INSTALL\C0NF1G.SYS 

C:\CONFIGJST 

C:\CMUB\SYSLEVELACS 

C:\EPVTQ0L\SYSLEVEL.EPV 

C:\EP\ASYSLEVELEPV 

C:\OS2\SYSLEVELEPV 

C:\SYSLEVELEPW 

C:\OS2\SYSLEVELEPW 

C:\TESTFFST\SYSLEYEL.EPW 

C:\0S2\INSTALIY3YSLEVELEPW 

C:\OS2\SYBLEVEL.EXE 

C:\MUGLIB\SYSLEVEL.MUG 

C:\0S2\INSTALL\SYSLEVEL.O32 

C:\IBMLAN\SYSLEVEL.REQ 

C:\SYSLEVELSNP 

C:\TOOLKT13\SYSLEVEL.TLK 


Figure 4: SmpDiunp data list 


any name in the File Name entry field; the 
dump formatter will assess whether the 
selected file is a SnapDump or FFST/2 dump 
file. 

Once a dump file and the Open button are 
selected, the Dump Formatter window will 
display the formatted SnapDump data and a 
list of captured data. Figure 3 shows the Dump 
Formatter window. 

The first field in the window names the dump 
file currently being displayed (here, 
SNAPDUMP.DMP), 

The second field in the window identifies a 
dump segment. If the SnapDump file contains 
more than 300 data entries (such as capture 
files, output from programs, or shared 
segments}, it will be segmented. Use the down 
arrow to the right of the field to see and select 
the desired segment. 

The third field shows the date and time of the 
dump as well as the file's originating program 
(in this case, "SNAPDUMP"), 


The fourth field contains the selected data 
item. When the Dump Formatter window is 
first displayed, "Process Environment" is 
preselected. The environment information 
collected by SnapDump includes PATH:, 
DPATH:, and so on. To get a complete list of 
captured items, click the down arrow or press 
Enter, Figure 4 shows a data list. 

When the Dump Formatter window is first 
displayed, the sixth field contains an ASCII 
representation of the Process Environment. 
The data can be displayed in one of three 
formats (use PF12 to toggle between data 
views): 

* Hexadecimal plus ASCII (Figure 5) 

* Hexadecimal plus EBCDIC 

* ASCII only (Figure 3) 

In Figure 4, a data item is selected for display 
by either clicking on the data item and 
pressing Enter or double clicking on the item. 
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Pomp Formatter 


File Options Help 

SNAPDUMP.DMP 

IBM SnapDump/2 Section 1 

05-06-1992 11:22:02.28 SnapDump 


C:\OS2\EPW.INI 


Offset 


Hexadecimal 


Translation 


00000000 

FFFFFFFF 

14000000 

15010000 

00000000 



00000010 

00000000 

00000000 

2COOOOOO 

00000000 



00000020 

04000400 

20000000 

43464700 

4BOOOOOO 

....(.,.CFG.K,.. 


00000030 

00000000 

04000400 

44000000 

03000300 

.D. 


00000040 

48000000 

4D5347Q0 

4F4E006A 

00000000 

H. .,MSG, ON,j_ 


00000050 

00000004 

00040063 

00000003 

00030067 

..c 9 


00000060 

00000058 

53440031 

35008900 

00000000 

.,,XSD.15. 


00000070 

00000400 

04008200 

00000300 

03008600 



00000080 

00005341 

44003132 

0QB4OOGQ 

00000000 

.,XAD,12........ 


00000090 

00040004 

OOAIOOOO 

000F00QF 

00A500O0 



OOOOOOAO 

00534450 

00433A5C 

4F53325C 

53595354 

.SDP.C:\0S2\SYST 


OOODOOBO 

454D5C00 

DFOOOOOO 

00000000 

04000400 

EM\. 


OOO0GOCO 

ccoooooo 

OFOOOFOO 

00000000 

41445000 

. .. .. P .ADP. 


OOOOQODO 

433A5C4F 

53325C53 

59535445 

4D5C0000 

C:\0S2\SYSTEM\.. 


OOOOOOEO 

00000000 

00000004 

000400F7 

□ 000001A 



OGOOO0FO 

001A0OFB 

0000004D 

4C4E0043 

3A5C4F53 

.MLN.C:\0S 


00000100 

325C5359 

5354454D 

5C4F5332 

4D4C4F47 

2\SYSTEMS0S2ML0G 


00000110 

2E444154 

00 



.DAT, 

T 



Figure 5: Dump formatter window in Hexadecimal pins ASCII format 


The F4 key (or clicking on the down arrow) 
toggles the visibility of the list box of the 
prompted entry fields whenever the entry field 
has the keyboard focus. To select an item from 
the dump or entry lists, use the arrow keys or 
the mouse, and double-click on the entry field. 
When a new entry is selected, it will be 
formatted and displayed. 

items in quotes represent programs invoked 
by SnapDump. Output from these programs 
can be viewed as you would view a file. 

Files captured in a SnapDump output file may 
be copied to disk with the SAVE AS command. In 
the SAVE AS dialogue box, set '"Select output 
type" to binary data. Files such as 052.INI, for 
example, should be saved as binary data to 
preserve their format. This function will not 
capture OS/2 Extended Attributes, 

Multiple SnapDump files can be opened with 
the Open command. 


Transporting SnapDump Output Files 

If a SnapDump file is too large to fit on a single 
disk, you can use the Backup function of OS/2 
to store it on multiple disks. Conversely, the 
Restore function can consolidate disk-spanning 
information into a single file. 

PROBLEMS SOLVED WITH 
SNAPDUMP 

A user with software problems often needs to 
capture problem-related information 
requested by support personnel, SnapDump 
does much of this work, locating and 
gathering diverse files. 

SnapDump can perform Problem 
Determination /Problem Source Identifier 
work. For example, if a customer running the 
IBM ES Communications Manager for OS/2 
changes the STARTUP.CMD to use a different 
configuration file and forgets he or she has 
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SnapDump/2 
can capture 
problem 
elements from a 
remote location, 
then analyze 
them offline 
zvhile the remote 
system 
continues 
processing. 


done so, it could cause the Communications 
Manager to run incorrectly. Forgetting the 
changed configuration files, the customer calls 
a support team, which requests eight files 
scattered across several directories. With 
SnapDump, the customer can easily collect all 
files for comparison, including the 
configuration file from the previous day. 

In a second example, a SNAPDUMP.DAT file 
can be edited to capture specific files needed to 
resolve a problem (executable code, 
configuration files, and error data file) and sent 
to a user, who simply returns the collected files 
to his or her support team for review and 
repair. 

Companies with internal support personnel 
will find SnapDump/2 valuable, as it can 
capture problem elements from a remote 
location, then analyze them offline while the 
remote system continues processing. 

In the final example, a change to the 
CONFIG.SYS hangs the system during the IPL. 
To create a dump file in SnapDump/2: 

* Execute IPL from the A: drive with the 
install disk 

* Hit Enter to continue or ESC to cancel the 
operation 

• With SnapDump/2 installed either on the 
C: drive or from a disk, execute 
SNAPDUMP, 

3NAPDUMRDMP will be captured and 
placed on a disk to be viewed from a fully 
initialized OS/2 system. After being identified, 
the problem may then be corrected and the 
system RelPLed. 


Michael Garrison, IBM Personal Systems 
Programming Center , 11400 Burnet Rd w Austin , 
Texas , 78758. Garrison is an advisory programmer 
for Extended Services for the OS/2 
Communications Manager. He joined IBM in 1979 
and initially worked on the 5520 Administrative 
System as well as serving as the development lead 
for the SNA Distribution Services (SNA/DS) 
feature of the 5520. In recent years , he has worked 
as a designer and developer for the IBM OS/2 
Extended Edition and Extended Sendees 
Communications Manager. He received a B.S. in 
computer science in 1977 and a master’s degree in 
computer science in 1979, both from the University 
of Southwestern Louisiana. 

Cecil W. (Bill) Rogers, Sr, IBM Personal 
Systems Programming Center , 11400 Burnet Rd. t 
Austin, Texas, 78758. Rogers is a staff programmer 
for FFST/2 and IBM SnapDump/ 2. He joined IBM 
in 1965 and initial}}/ worked on Manned Space 
Systems in Houston, Texas , He then served as the 
lead on RASfor Navy submarines in Massanas t 
Va, t coded RAS on the Displaywriter, and led 
development of SNA management function for 
Communication Manager. He received an A.A. in 
computer science from San Jacinto College. 


OBTAINING SNAPDUMP/2 

IBM SnapDump/2 presently resides on 
OS2TOOLS for IBM internal personnel. 
Customers can get SnapDump/2 from the 
National Support Center (NSC) Bulletin 
Board System by phoning 404-835-6600, In 
Canada, phone 416-946-4244 (9600 bps) or 
416-946-4255 (2400 bps). 

SnapDump/2 is included with IBM 
Extended Services for OS/2, ESDTOOLS 
and Field Tool Warehouse. 


SUPPORT FOR SNAPDUMP/2 

User support for customers and SEs is 
provided through EQUAL/ASKQ. 
Keyword for entries should be 
"SNAPDUMP". 

Defect support is handled through 
SNAPDUMP FORUM on IBMPC. Calls 
regarding defects will be answered within 
two weeks. 
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Customize 

communications. 


Quadron’s development tools for OS/2 
provide the flexibility you need for 
custom co-processor communications. 

Match your protocols. 

Use IBM ARTIC intelligent co-processor 
cards when you need extra ports or want 
to off-load protocol processing from your 
host computer. Then use Quadron soft¬ 
ware for custom communications with 
proprietary protocols, async, BISYNC, 
HDLC, X.25, and LAP-B. And if you need 
more than one protocol, no problem—just 
run them together on one card—at the 
same time. 

IBM and OS/2 are registered trademarks of IBM Corporation, 


Write & debug with ease. 

You’ll feel right at home with Quadron 
software. Just program in standard C, and 
use our messaging API to link OS/2 
threads with tasks on the card. Then use 
our symbolic debugger and real-time 
analysis tools in OS/2 windows. 

Protect your investment. 

Perhaps best of all, our software is port¬ 
able. Run what you write on any ARTIC 
card, on either ISA or Micro Channel. 

And if you later switch operating systems 
or platforms, just recompile. 


Fit your applications. 

Our easy-to-use software serves applica¬ 
tions as diverse as telephone switching, 
financial transactions, satellite communi¬ 
cations, and process control. 

So call us, We've got an OS/2 commu¬ 
nication solution—cards and software 
tools—ready to serve you today. 

Quadron 

Quadron Service Corporation 
209 East Victoria Street 
Santa Barbara, CA 93101 

805 - 966-6424 
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TO A PRINTER! TO THE CLIPBOARD! TO A FILE! 


MITNOR Software 
28411 E. 55th Street 
Broken Arrow, OK 74014 

Phone: (918) 357-1628 
Fax: (918) 357-2869 



PrntScrn 11 is THE One-Step Screen Image Utility 
for copying a graphics image from the Workplace 
Shell screen to a LAN or locally attached printer, to 
the Clipboard, or to a disk file. The screen images 
appearing in this publication were captured and 
processed using the PrntScrn utility. The capture 
operation can be initiated from the keyboard (by 
pressing the print-screen key), from the mouse, or 
from another program. The captured image area 
can be the entire screen, current active window, 
current active client area, selected window, selected 
client area, or specified rectangular area. Disk file 
formats include PM Metafile, PM Bit Map, PCX, 
TIFF, GIF, and WPG. The "Color Mapping" 
feature provides the control needed to produce 
quality printed images from color screen images. 
PrntScrn has clipboard Viewing. Printing, 
Exporting, & Importing capabilities for Bit Maps, 
Metafiles, and Text files. PrntScrn includes a 
Screen Blanker and a digital Date & Time 
"information bar". PrntScrn is priced at $115 and 
is available from major software resellers, 
or contact MITNOR Software. 
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32-Bit OS/2 

Applications Printing 
Using OS/2 2.0 



Michael Perks 


In/ Michael Perks 

Tins article describes how an application should 
print using OS/2 2.0. Most of the concepts and 
ideas presented here are also applicable to OS/2 12 
and 13. Only 32-bit APIs have been used in the 
programming examples. The text and 
programming examples have been extracted from 
the OS/2 2.0 Technical Library; Programming 
Guide Volume III, Chapter 18. Corrections have 
also been made to the original text. 

It is strongly recommended that you obtain the 
OS/2 2.0 Toolkit so the sample print program 
P RTS AMP can be examined for implementation 
detail of all the concepts presented here. The 
methods ami recommendations should be foil owed 
whenever possible. This leads to consistency among 
OS/2 applications. 


42 


USER DIALOGUES 

T here are several stages involved in using 
the PM programming interface to print 
your application data. From a user-interface 
point of view, the following four dialogues 
must be provided. The exact order in which 
these dialogues are used will govern the order 
of program execution. 

Page-Setup Dialogue 

The page-setup dialogue lets users specify the 
fortn name or size required. Options on this 
dialogue can include margins on the page, 
header and footer strings, and whether duplex 
formatting is required. 

The actual contents of the dialogue depend on 
the type of application. This page must specify 
formatting options that also are used to 
display to a screen. 


Printer-Setup Dialogue 

The printer-setup dialogue displays a list of 
queues available to the user. A job-properties 
button on this dialogue lets users query and 
modify the job properties for this job. 

Font Dialogue 

Most PM applications must allow users to 
specify the font (or fonts) required. Once they 
have chosen a printer, an option on the fonts 
dialogue lets users choose from device fonts, 
as well as system fonts. 

Print Dialogue 

The application should have a Print menu item 
on the File menu to invoke an application- 
specific print dialogue. It is recommended that 
the Shift-PrintScreen key be used as an 
accelerator for printing the client area. The 
PrintScreen key, unshifted, is used to capture 
and print a window or the whole screen. 


PAGE-SETUP DIALOGUE 

The page-setup dialogue is concerned with 
formatting options for the document. Users 
must be able to specify the form name, 
margins, and other application-specific 
formatting options such as page duplexing; 
that is, different formats for left and right 
pages in a multipage document. Figure 1 
show's an example of a page-setup dialogue. 

The application is responsible for storing the 
user-defined margins for the form and must 
not allow users to specify margins smaller 
than those returned by the printer driver. 
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FORMS SELECTION 

If the user has not chosen a specific printer, the 
application can supply a list of standard form 
sizes; for example, letter, legal, ledger, A4, and 
A3. The application also must consider, at a 
minimum, a 0.4 inch (10 mm) margin on the 
form to be within the hardware clip limits of 
most printers. Table 1 shows the most 
common form sizes. 

When a printer is chosen, it must be queried 
for the forms and hardware clip margins it 
supports using DevQueryHardcopytaps. First 
however, a device context must be created. It is 
recommended that a QDJXYFO context be used 
because 0D_QUEUED can result in the creation of a 
print job. Figure 2 shows a sample code 
fragment. 

Dev Query Hardcopy Caps returns one HCINFO 
structure for each form. The contents of the 
structure are: 

* ASCII name of the form (for example. Letter) 

* Width and height (in millimeters) of the 
paper 

* Clipping limits (in millimeters) of the paper 

* Number of pels between clipping limits 

* Whether this form is the one installed 
currently on the device, or whether it is 
selectable from another paper bin. 

Then, the list of forms can be displayed to the 
user. The form preselected in the list should be 
one of the forms marked with the HCINFO 
structure flag HCAPS_CURRENT 

An application should indicate to the user 
which forms are currently installed in the 
printer by including the HCINFO structure flag 
HGP5_SEIECTABLE. Then, users can decide 
whether they want to print quickly on a form 
available from the printer or to install a 
different paper tray in the printer. 


PRINTER-SETUP DIALOGUE 

In a printer-setup dialogue, an application 
should offer a list of available printer objects 
and let the user select one, (The list of printer 


objects actually is a list of queues.) If none is 
available, an appropriate message must be 
displayed. An application must query the list 
of available printer objects each time the 
printer-setup dialogue is displayed because 
the user might have created or modified the 
printer configuration while the application 
was executing. Figure 3 shows an example of a 
printer-setup dialogue. 

If the document was formatted for a particular 
device and the user selects a different printer, 
the application must ask the user's permission 
before reformatting the document for the new 
printer. 




Figure 1: Application page-setup dialogue 


COMMON FORM SIZES 


Form Name 

Size in inches 

Size in mm 

Letter 

8.5x11 

216 x 279 

Legal 

8,5 x 14 

216 x 356 

Ledger 

11 xl7 

279 x 432 

A4 

8.3x11.7 

210 x 297 

A3 

11.7 x 16.5 

297 x 420 


Table I: Common form sizes 


Use SplEnumQueue to query the list of printer 
objects; printer objects essentially are spool 
queues. SplEnumQueue returns a list of queues 
and information about each queue on the local 
workstation in an array of PRQXNF03 structures. 
It also returns information about local 
workstation queues that reference network 
print queues. 
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PPRDINFQ3 pprd3Devi.ee; 

/* From SplQueryDevice 

*/ 

PPRQINF03 pprq3Queue; 

/* From SplQueryQueue 

*/ 

PSZ pszTmp; 

/* Temporary pointer 

*/ 

HOC hdc; 

/* Device context handle 

*/ 

OEVOPENSTRUC dopData; 

/* DEVQPEN structure 

*/ 

LONG clForms; 

/* Number of forms 

*/ 


/* The device 

*/ 

PHCINFO pchinfo; 

/* Forms information 

*/ 


/* structure 

*/ 

ULONG ulrc=DEV_DK; 

/* Return code 

*/ 

/* Fill in data for devopendata for 0D_INFD 
dopData.pszLogAddress = pprd3Device->pszLogAddr; 

*/ 

pszTmp - strchKpprqBQueue^pszDriverName, 
if (pszTmp) 



♦pszTmp = ‘VO 1 ; 



dopData.pszDriverName = pprq3Queue->pszDriverName; 


dopData.pdriv = pprq3Queue~>pDriverData; 



/* Open the information device context 


*/ 

hdc = DevOpenDC ( (HAB>0, 



QD_INF0, 

/* Type 

*/ 

n^ii 

/* Default token 

*/ 

3L, 

/* Count 

*/ 

tdopData, 

/* Pointer to data 

*/ 

(HDC)O); 

/* Comp dc 

*/ 

/* Query number of forms available on the device 

*/ 

clForms = DevQueryHardcopyCaps(hdc, 



OL /* Start at beginning of list 

*/ 

OL, /* Get number of forms 

*/ 

NULL); 



/* Allocate memory block for forms 


*/ 

if (DosAllocMem((PPYOID(&pchinfo), clForms+sizeof(NCINFO), fALLOC)) 
s 


DevCloseDC(hdc); 
return(PEV.ERRQR); 

} 



/* Query forms data 

ulrc - DevQueryHardcopyCaps(hdc, 


*/ 

01, /* 

Start with first form 

*/ 

clForms, /* 

Query all forms 

*/ 

pchinfo); /* 

Structure to hold returned */ 

/* 

data 

*/ 

/* Close the information device context 


*/ 

DevCloseDC (hdc); /* 

Close the information 

*/ 

/* 

device context 

*/ 

/* Now use forms information in pchinfo 


*/ 


Figure 2: Querying the printer using DevQuery Hardcopy Caps 
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Because the number of queues might vary for 
each application use, it is essential to allocate 
sufficient storage to hold the data returned by 
SplEnumQueue. Usually the application issues the 
query twice. The first time, the application 
determines the necessary size of the 
information buffer. After allocating a memory 
block, the second query actually retrieves the 
information* 

The queue description (returned in the 
structure PRQINFQ3 field name pszConiment) is the 
printer object title. This command is much 
more familiar to users than the queue name, 
which is displayed only on the view settings 
page of a printer object. Therefore, the printer- 
setup dialogue should show the queue 
descriptions instead of the queue names. 

SplEnumQueue returns information about the 
queue that might influence the user or 
application's decision to print to this queue; 
for example, the number of jobs already in the 
queue* SplEnumQueue also returns the default job 
properties for the queue. This data can be used 
by the application for the job-properties button 
on the printer-setup dialogue* 

JOB-PROPERTY 

CONSIDERATIONS 

Job properties are options on a per-job basis; 
for example, orientation, resolution, and form 
selection. The job-properties dialogue is 
displayed by the printer driver. Each driver 
has a different dialogue, depending on the 
capabilities of the printer. The job properties 
are held in a printer-driver-specific format in 
the abGeneralData field of the DRI YD AT A structure* 

Job properties from one printer driver should 
not be given to another printer driver. The job 
properties probably will not be understood, 
and the printer driver will either return an 
error or substitute some default job properties. 
Then, the user will see a change in job 
properties stored previously. 

Users should be given the opportunity to 
change the job properties before the job is 
printed* This can be achieved by supplying a 
job-properties push button on the printer- 
setup dialogue. 


Retrieving fob Properties 

Tire application can retrieve job properties 
from the following locations: 



* Previously saved job properties with the 
document 

* Current application session job properties 

* Default job properties from the queue (from 
pDriverData in the PMJHF03 data structure) 

* Printer drrivr device defaults (from 
DevPostDeviceNudes using the DPDM^QU ERY J08PR0P 
flag). 

'ill ; 1 



Figure 3: Application printer-setup dialogue 


If no job properties were saved with the 
document, there may be job properties being 
used by another document that is to be printed 
to the same queue. 

If job properties still cannot be found, the 
default job properties stored with the queue 
can be used. The user may not set up any 
default job properties for the queue. Finally, 
query the printer driver for its device defaults 
using DevPostDeviceModes with the 
DPDH_QUERY JOBPROP flag. 

The sample code in Figure 4 shows how to 
display the job-properties dialogue. All the 
parameters required are available from the 
PRQBJFQ3 structure returned by SplEnumQueue or 
SplQueryQueue, 
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200 #define INCL.DEV 
tdefine INCL.DQS 
•include <os2,h> 

•include <memory.h> 


{ 

ULDNG ulre=FALSE; 

BAB hab; 

PPRQINFG3 pprq3tjueue; /* From SplEnumQueue or SplQueryQueue */ 

PSZ pszDriverName,pszDeviceHame,pszTmp; 

HOC hdc=NULL; 

LONG cbBuf; 

/* Use the first device name in the PRQINF03 structure 
pszTmp = strdir(pprq3Queue->pszPrinters, 
if (pszTmp) 

*pszTmp = r \0 J ; 

*i 

/* Use just the driver name from the driver,device string 
pszDeviceName = strchr{pprq3Rueje->pszDriverName i V); 
if (pszOeviceName) 

{ 

♦pszDeviceWame = 'W; 
pszOeviceName++; 

} 

*/ 

/* Check size of buffer required for job properties 
cbBuf = DevPostDeviceModes( hab, 

(PORIVDATA)NULL, 
pprq3Queue->pszDriverName, 
pszOeviceName, 
pprq3Queue->pszPrinters, 
DPDN.POSTJOBPROP 

); 

*/ 

/* Return error to caller 
if {cbBuf<=0) 

return(cbBuf); 

*/ 

/* Return BUFFER TOO SHALL error to caller 
if (cbBuf > pprq3Queue->pDriverData->cb) 
return(OPOM_ERR0R); 

*/ 

/* Display job properties dialogue & get updated job props 
ulrc = DevPostf)eviceHodes( hab, 

pprq3Queue->pDriverData, 

pprq3Queue->pszDriverName, 

pszDeviceName, 

pprq3IJueue->pszPrinters, 

DPDM_P0STJ0BPR0P 

from driver */ 

return(ulrc); 

} 



Figure 4. Displaying the job properties dialogue 
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FONT DIALOGUE AND DEVICE 
FONT CONSIDERATIONS 

There are two types of fonts: 

* System fonts, which can be used for displays 
and printers, and therefore, are generally 
more flexible. 

* Device fonts, which are specific to a 
particular device. Device fonts for printers 
can be built-in or installed with font 
cartridges by a user. Device fonts can also be 
available on disk (also termed soft fonts) and 
downloaded to the printer as required by the 
printer driver. 

The advantage of device fonts is that they are 
usually printed in the highest resolution of the 
device and are faster than system fonts. 

Some printer drivers, in particular the HP 
LaserJet (LASERJET) and the LaserPrinter 
(IBM4019) printer drivers, provide an 
intermediate solution. An option on the job- 
properties dialogue enables system fonts to be 
downloaded to the printer as soft fonts. 

An application must provide users with the 
ability to choose fonts and, in particular, to 
choose a device font over a system font to 
achieve better performance. A standard font 
dialogue box should be used, such as 
WinFontDXg. 

When an application uses device fonts and the 
output mixes text and graphics, the device 
fonts are clipped per character. System fonts 
give more precise clipping to the pel. Figure 5 
illustrates the results from clipping two lines of 
text: one generated in a system font, the other 
in a device font. 


printing, query the printer driver and attempt 
to choose a device font that closely matches the 
system font. If no match is found, then print 
using the system font. A devices font's metrics 
and character spacing might not match exactly, 
so the printed output might not be exactly the 
same as the display. 

Second, use a printer font if the user selects 
one. Determine the metrics and find a system 
font that shares the same characteristics (for 
example, a style such as Courier or Serifed). 
The character string to be displayed is sent to 
the printer driver and the intercharacter 
spacing is returned, using 
GpiQueryCharStringPos. The individual character 
positions are used when the string is sent to 
the display, using GpiCharStringPos with the 
Options parameter of CH3_VECT0R. While the 
display output can take longer to display to 
the screen, true WYSIWYG (What You See Is 
What You Get) is achievable. 




Clipping Boundary 

1 

VBCDE 

J_ __ ___> 

System Font 

Device Font 

IBCC 

BC 


Figure 5; Cham ter clipping results for device and system fonts 


The available device fonts can be queried, 
using GpiQueryFonts in either an OD.INFO or 
OD_QUEUEO device context. Device fonts are 
returned with negative IMatch numbers. Then 
the appropriate logical font can be used after 
issuing GpiCreateLogFont. 

If, during the printing process, a logical font is 
not created, the printer driver uses its default 
font for the printer, which is usually 12-point 
Courier 

There are two design choices for device fonts. 
First, use system fonts for the display. When 


PRINT DIALOGUE AND 
PRINT PROCESSING 

The print menu must display a dialogue to 
allow the user to specify the number of copies, 
start page, end page, or any other application- 
specific print options. A confirm button 
initiates the print. Figure 6 is an example of a 
print dialogue. 

The Printer entry field is the read-only name of 
the printer object (queue) the user chose from 
the printer-setup dialogue. The Preview 
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checkbox is used to preview the printed 
output on the screen. This can be achieved by 
opening an 0D_HEM0RY device context to the 
printer driver and drawing the picture into the 
bit map, A Bit Bit to the screen shows the 
resulting page. System fonts should be used 
instead of device fonts. 



Printer 

Document 



Copies ■ 
□ Preview 


OK 


Cancel 


Help 


Figure b Application-Print dialogue 


The following sections describe each of these 
steps. 

Creating a Nezv Thread 

Once the print process has been confirmed by 
the user, the application must use a separate 
thread to perform the actual printing. This 
maintains user responsiveness and avoids 
displaying the hourglass pointer. While the 
printing is in progress, the application should 
dim certain menu options, such as drawing. 
Other options, such as page down, zoom, or 
help must stilt be available. 

Opening a Device Context 

Before you can send data to a printer using 
device functions, you must open a device 
context with DevDpenDC The parameters of 
DevGpenDC are influenced by the queue and job 
properties the user has chosen previously, 

OevOpenDC accepts the following parameters as 
input: 

* hab—the anchor-block handle from a 
Winlnitializecalh 
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Once the user has initiated the print, a PM 
application must execute the following steps: 

1 Create a new thread. 

Then, on this new thread: 

2. Open a device context. 

3. Associate a presentation space. 

4. Start the print job. 

5. Query the device capabilities. 

6. Format the page. 

7. Start the next page. 

Repeat Steps 6 through 7 for each page. 

8. End the print job. 

For another print job, repeat from Step 4. 

9. Disassociate the presentation space. 

10, Close the device context. 


* lType—the type of device context. This is 
always Ot)_QUEUED to specify a queued device 
context. 

* pszToken—the device-information token. 
Always use an asterisk (*) for this parameter 
to force the system to get device information 
from the pdopData parameter, 

* ICount—the number of data elements 
supplied in the pdopData parameter. The 
minimum number of parameters for a 
queued device context is four. 

* pdopData—the device-context data area. This 
is a pointer to a structure of the type 
DEVQPENSTRUC The DEVOPENSTRUC structure 
contains all the data needed to define a 
device context. At least the first four 
structure members must he provided for 
queued device contexts. 

* hdcComp—the compatible device-context 
handle. This must be NULL for a device 
context of the type Q0_QUEUED. 

DevOpenDC returns a device-context handle of 

the type HDC. The handle is used in other 


i 




















Summer 1992 


functions beginning with the Dev prefix, and 
for GpiCreatePS and GpiAssociate. 

The DEVOPENSTRUC structure contains all 
the data needed to define a device context. Its 
individual elements are described below. At 
least the first four structure members must be 
provided. 

* pszLogAddress is the name of the queue. It is 
the pszNsme field of the PRQINF03 structure. For 
device contexts of the type OD^XNFO, 
pszlogAddress is the port name. This can be 
retrieved by calling SplQueryDevice using the 
pszPrinters device name. The pszLogAddr field 
in the PRDDIFQ3 structure is the port name. 

* pszQriverNafne is the character string 
identifying the printer driver, for example, 
LASERJET The pszDriverName field of the 
PRQINFQ3 structure associated with the 
required print queue gives the driver and 
device name, separated by a period, for 
example LASERJET.HP LaserJet IIID. The 
pszDriverName field can contain only the name 
up to the period, for example LASERJET. 

* pdriv is a pointer to the job-property data 
returned by the printer driver from 
DevPostDeviceModes or the default job 
properties from pDriverData in the PRQXNF03 
structure. The DRIVDATA structure contains the 
particular device name to be used. 

Therefore, it is a programming error to set 
this parameter to NULL. 

* pszDataType is a data type, it is recommended 
that "PM JLSTD 1 ' be used here. 

* pszComment is an optional character string the 
printer object displays to the user in a job- 
settings notebook. The application should 
include its own name in this comment 
string. The job title text is derived from the 
document name. 

* psztJueueProcName is an optional queue 
processor name. The queue processor (also 
termed "queue driver") name is available 
from the pszPrProc field of the PRQINFD3 
structure. The default queue processor 
provided by the operating system is PMPRINT. 
The user also can install a queue processor 
(PMPLOT) used to provide reverse clipping for 
vector devices such as plotters. 


* pszQueueProcParams are optional queue 
processor parameters. They can include 
information such as the number of copies 
you want to print and the size of the output 
area on the printed page. 

* pszSpoolerParafns are optional spooler 
parameters separated by spaces. They are 
used for scheduling print jobs, such as the 
form names that identify the paper to be 
used, for example, FORMATTER. 

* pszNetyorkParams is an optional parameter 
that can be used to specify network options, 
for example, U$ER=JDESMITH. 

Associating a Presentation Space 



To print, a device context must be associated 
with a GPI presentation space. In most 
circumstances, a presentation space already 
exists for the screen. In such cases, the 
presentation space can be disassociated from 
the window device context and associated 
with the printer device context by rising 
GpiAssociate. 

If a presentation space does not exist, or a 
different one is to be used, the application 
must issue GpiCreatePS and use the GPI ASSOC 
flag to associate the printer device context. 

Device-Independence Considerations 

The operating system supports true 
WYSIWYG. The same CPI functions the 
application used to create the picture or 
document on the display screen can be used to 
create the output on a printer. This is the major 
advantage of device independence. 


An application 
must be 

designed around 
the options 
provided by the 
PM 

programming 
interface to 
ensure device 
independence. 


An application must be designed around the 
options provided by the PM programming 
interface to ensure device independence, as a 
display (VGA) typically is % dpi, while a 
printer typically is 300 dpi. 


Some application design considerations apply. 

Use DevQueryRardopyCaps to determine the size 
of the form and the maximum printable area. 

Create a presentation space with a 
presentation page size of 0 to ensure that the 
maximum window and page size are used. 

Use device-independent coordinates, such as 
LO ENGLISH or TWIPS. If you program in pels, 
transferring your output from screen to 

hardcopy will compress the picture. ^ 
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Starting a Print fob 

The application signals the beginning of a 
print job by using evEscape with the escape 
parameter 0EVESC_STARTDOC. The application 
must specify a document name, usually 
related to the name of the file being printed. 
Any GP1 calls made before this 
De v Escape (DEV ESC JT A RTDQt) are ignored. 

Querying the Device Capabilities 

DevQueryCaps can be used to provide over 40 
pieces of information about a specific device; 
for example, default character box size, 
horizontal and vertical resolution, or number 
of device-specific fonts. Knowing the device 
has only 1-bit color support (monochrome) 
might influence the application to use line 
style and patterns instead of colors for output 

Formatting Pie Page 

Before print processing actually starts, it is 
recommended that an application modal 
dialog be used to show page progress and 
allow the user to cancel the print job. If the 
user presses cancel on this dialogue, the 
application must issue Dev Escape with the 
parameter DEVESCA80RTD0C, This command 
enables the spooler and printer driver to clean 
up. A job is not created in the queue. 

Usually, the output on a page is generated by a 
series of GPI calls from the application. The 
application must be able to decide when to 
move to the next page in a multipage 
document by calculating the size of character 
strings or graphics written to the presentation 
space. 

Starting the Next Page 

When the application has finished processing a 
page, it must issue De v Escape with the 
DEVESC.WEWFRAME parameter. The progress 
dialogue must be updated. 

The DevEscape DEVESC JEWFRAME can be used to 
generate blank pages. The printer driver 
always issues a page eject whenever this 
Dev Escape is received. Issuing the DEVESC JEUFRAME 
escape does not reset any attributes or fonts. 
However, the bounds and any clipping 
regions are reset. 


Ending the Print Job 

The end of a print document is signalled by 
the application's issuing DevEscape with the 
DEWESC^ENDDOC parameter. The spooler returns a 
job identifier that can be used for job 
manipulation. 

Disassociating the Presentation Space 

When the print job is complete, the 
presentation space can be disassociated from 
the printer device context using GpiAssociate 
with a NULL parameter. Then the presentation 
space can be reassociated with the display 
device context. 

Closing the Device Context 

A device context is closed using DevCloseDC, The 
print thread must signal print termination to 
the main processing loop. The main loop can 
terminate the print thread and dismiss the Page 
Progress message box. 

An application can display a message box to 
the user indicating a successful print and show 
the job ID returned by the spooler. 

PRINT TO FILE CONSIDERATIONS 

Print to file means that the print data 
destined fora printer is stored in a file instead. 
The advantage is that the file can be used later, 
possibly on a different machine or 
environment, and the data can be printed 
without requiring the original application. 

The preferred method to print to file is for the 
user to specify Print to file on the Output 
settings page of a printer object. When a print 
is requested, the system displays a dialogue in 
which the user can enter a file name. The 
application does not have to he aware of the 
print to file; the user has full control of the 
system, 

NETWORK PRINTING 
CONSIDERATIONS 

The PM architecture requires a printer driver 
during the print job creation process to deal 
with queries such as DevQueryHardcopyCaps and 
to provide the job-properties dialogue by way 
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of DevPostDeviceModes. To do any printing across 
a network, a locally installed printer driver is 
required. In some cases, such as when the 
network server does not run PM, this is an 
advantage because all the conversion-to- 
printer specific commands can be done on the 
requestor. 

The printer object in the workplace provides 
seamless access to network printers; the user 
need only install the appropriate printer 
drive*. 

The application programmer is also helped, A 
network printer accessed by the user has a 
hidden shadow on the requestor. The job 
properties for the shadow printer object can be 
altered and are stored on the requestor. This 
capability enables the user to configure one or 
more variations on the original configuration 
without requiring intervention from a system 
administrator to create many network printer 
objects, each with a slightly different default 
job-property configuration. 

The shadow printer object is created on the 
requestor by creating a local queue and local 
device with no port connection. The 
application can enumerate these queues using 
SplEnumQueue, The only difference is in the 
PRQ1NF06 structure; there are two extra fields 
not in the PRQINF03 structure. These two 
extra fields, called pszRemoteCorripu ter Name and 
pszRemoteQueueName, contain the name of the 
remote server and queue. The spooler uses 
these fields to automatically reroute print data 
submitted by an application to the local 
shadow to the appropriate network queue. 

The printer object creates a local shadow only 
when the network print object has been used 
or modified because there could be a large 
number of network printer objects, and the 
spooler does not know which one the user 
wants to use. The local shadow of a network 
printer object is created in these cases: 

* When a file is dragged and dropped on the 
network printer object 


DRAG/DROP PROTOCOL 
CONSIDERATIONS 

When an application data file is dropped on a 
printer object, the application can receive a 
DM_PRINTQBJECT message if the application is 
running currently. 

One Dfl.PRINTQBJECT parameter gives a 0RAGINFO 
structure that describes the object dropped. 

The other parameter gives a PRBITDE5T structure 
that contains all the parameters required to 
issue DevPostOevIceMades and DevGpenOC, 

The PD_J0B_PR0PERTY flag indicates to the 
application that the user has requested a job- 
properties dialogue before printing. If this flag 
is not set, the application must not display the 
job-properties dialogue; it must use the job 
properties passed in the PRINTDEST structure. 

The rest of the printing process follows the 
proced u re d escri bed prev i o us 1 y. 

Michael Perks, /BM Carp, Internal Zip 1510 , 
1000 N.W. 51st St., Boca Raton, Fla. 33431 . Perks 
is a project programmer in OS/2 Printing 
Development , He is the designer for the OS/2 2.0 
Print Subsystem and the OS/2 2.0 LAN 
independent shell. He joined IBM in 1984 and has 
been working on OS/2 since 1986. He received a 
BSc. from Loughborough University of Technology 
in Loughborough, U. K. 
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* When the network printer object is moved, 
copied, or shadowed outside its original 
server folder 

* When the printer or job properties are 
modified. 
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32-Bit OS/2 

Where, Oh Where, 

Did the Print Manager Go? 

Printing with the OS/2 2.0 Workplace Shell 


by Abhy Gelles Knott 

If your software ran under OS/2 1.3, your 
customers might have needed help with printer 
setup or job management OS/2 2.0 provides a more 
intuitive print-subsystem interface than the 
procedure-oriented , menued OS/2 1.3 Print 
Manager, The OS/2 2.0 Workplace Shell empowers 
your application customer, to make some of the 
choices you used to program . By opening the 
various views onto simple desktop objects , anyone 
can tailor a configuration, check the progress of 
print jobs , and solve problems. In fact, the OS/2 2.0 
on-line help information urges your customer 
to do so ' 

This article will familiarize you with your 
customers view of printing under OS/2 2.0. In the 
previous article, “Application Printing Using OS/2 
2.0," Michael Perks provides many of the 
programming details you need to coordinate with 
the shell in protecting your customer's preferences. 
Perks designed the shell you are about to explore . 
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Figure I: Print object icon pm the desktop 


OVERVIEW—WHAT'S NEW? 

D id your customer have difficulty 
understanding the OS/2 1.3 Print 
Manager queues? Queues have little 
importance to the user of the OS/2 2.0 shell. By 
contrast you, the developer, focus more on 
queues (and less on devices or ports) than you 
might have previously. Queues have a new 
face and are tightly coupled with their fellow 
print mechanisms, printer drivers, and ports. 

A set of these items is packaged under an icon 
that looks like a printer, called a printer object. 
Figure 1 shows the OS/2 desktop with one 
printer object icon in its closed state. 

Each variation in the setup can have its own 
printer object. You might think of each printer 
object on a desktop as a mini-Print Manager. 
Figure 18-1 in the OS/2 Programming Guide 
shows how flexibly the printer-object 
mechanism permits queues and devices to 
support one another. Thanks to OS/2 2.0 LAN 
independence, your customer simply 
manipulates another printer object to print 
remotely, while you use the same APIs to 
communicate with a network printer object as 
you would with a local printer object. 

WHY SHOULD YOU BE 
CONCERNED WITH THE SHELL? 

Your program views the printer object as a 
print destination and does not concern itself 
with a physical device. The printer object looks 
like a printer even if it represents a setup that 
prints to a disk file. This abstract object is the 
printer your user selects when you ask, 

"Where do you want to route this job?" Your 
application should identify printer objects by 
their descriptive names, which might be 
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"Harry's printer/' "My printer for PostScript 
jobs/' not by their internal names, such as 
LPT1Q1, (You list the name pointed to with 
pszComment, rather than pszName for the queue, 
from PRQINFD3.) 


port address (LPT1). As you will see, a printer 
object can have multiple logical addresses or 
no port assigned to it. 

Port Configuration 



To the user, printer objects combine to form a 
personal setup. Because an application that 
ignores that setup or overrides it without first 
notifying the user can cause consternation, the 
remainder of this article provides a quick 
overview of that setup. To help you 
understand the relationship between objects in 
the shell and the printing thread in your 
application, this article references Perks' article 
and "Print Job Submission and Manipulation" 
{IBM, OS/2 Programming Guide , 1992). 


SETUP 

Initial Installation 

Selecting a printer during operating-system 
installation prompts the system to install the 
appropriate printer driver and create a printer 
object with that printer driver as its default. 
Installation also provides objects, blatantly 
displayed, that open onto on-line information. 
Within that information are step-by-step 
instructions for installing additional printers 
and drivers. 

Customization Settings ami Properties 

To adjust printing setup, your user changes 
printer-object settings. When the printer object 
is open to its settings view, the shell displays a 
spiral-bound notebook with a separate tabbed 
page for each category of setting. This section 
explains which of the user's choices on these 
pages influences your application. 

Output 

The output settings page, shown in Figure 2, 
enables a user to select and configure physical 
ports or to initiate a print-to-file command. 

Porf Installation 

A default system has parallel connections LPT1 
and LPT2 and serial connections C0M1 through 
COM4, but the pop-up menu for any port object 
on this page includes an option for installing 
other flavors. No matter what ports your user 
has, your program does not capture a logical 


To adjust the timeout period for a device, a 
user opens (double-clicks on) the connecting 
port object inside the Output port field. A 
window opens, exposing a Timeout setting field, 
which replaces "Printer Timeout Transmission 
Retry" in the setup-printer dialogue of the 
OS/2 13 Print Manager. This port setting 
takes on increasing significance with the 
proliferation of PostScript printers. Opening 
the object for a serial (COM) port also exposes 


COMPONENTS OF AN OS/2 PRINT SUBSYSTEM 

A system needs the following components before printing can occur: 

* The printer object is an icon that represents one print destination. 

The shell enables a user to drag any printable object to this object for 
instant queuing. The operating system enables your program to view 
each printer object as an integrated print destination. 

* The queue driver software assembles and distributes separate print 
jobs. 

* The printer driver software and information controls print-job setup 
and ultimately converts jobs to the format a particular printer model 
can interpret. Another name for the printer driver, as it applies to 
your Presentation Manager printing API, is presentation driver. Some 
of the developer documentation uses the latter term, 

* The output device is usually a printer that takes an image out of 
computer memory and imprints it on a tangible medium, such as 
paper. Actually, your program might interface with a printer, a 
plotter, a device that produces nonpaper media (such as film), a 
communications or fax modem through which you send print- 
formatted information, or a disk file containing a printer-ready 
version of a document. Because the print subsystem can print to a 
file, device hardware is optional. 

* The port is a 25- or 9-pin connector used to attach printers, plotters, 
and communications devices. 

* The spooler is where print jobs are actually held together in one 
area of the disk, the spooler path, which houses the print files for all 
printer objects. The shell contains a separate Spooler object, which 
represents the controlling program that manages queues. This 
object provides a means to change the location of the system spool 
file or to disable spooling for direct printing. 
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adjustable communications parameters such as 
baud, word size, handshake, and so on. 

Pooled Printers 

If a system has multiple printers, each 
connected to a different port, the system 
owner can improve throughput by selecting all 


Output to File 

A person who occasionally prints to a file 
creates a separate printer object and puts a 
check mark in the Output to file field. Any job 
routed to this particular printer object invokes 
a print-to-file dialogue that prompts for a file 
name. 



Frgitfi? 2; Output settings notebook page 



Figure 3: Printer driver notebook page 

those ports in the Output port field. All jobs 
queued at the printer object hav e several 
output possibilities and each, in turn, is sent to 
the first available port. Consider the benefits of 
this setup, called pooled printers, to the 
administrator of a LAN printer server. Again, 
since the user can pool printers, you do not 
want your application to query a logical port 
address or route output to it. 


Printer Driver 

This notebook page, shown in Figure 3, 
contains objects from which a user accesses the 
dialogues for adding printer drivers and for 
configuring printer properties, fonts, and 
default job properties. It is also on this page 
that a user designates a specific driver for use 
in printing. 

Default Driver 

If the system has multiple printer drivers 
installed, the user can change the driver 
assigned to this printer object at any time. 
Different drivers can potentially give the same 
output different looks, even when they are 
printed by the same physical device. 
Preferably, the user will create a separate 
printer object for each driver desired. The on¬ 
line information points out these subtleties in 
configuration and explains how to achieve 
them. 

Printer Properties 

A printer driver has a device-specific printer- 
properties dialogue for indicating the actual 
physical setup of a device, such as number of 
trays, forms used, and cartridges loaded. The 
on-line information instructs your user to 
make printer-driver selections after installing a 
driver and maintains these fields appropriately 
to match changes in loaded forms, font 
cartridges, plotter pens, or other resources. 
When your software allows the user to choose 
a document form and fonts, it references the 
printer-properties information to verify the 
availability of these job-specific requests. 

Opening the object in the Default driver field 
accesses the printer-properties dialogue. 
(Printer properties are really printer-driver 
settings, but the dialogues retain the look and 
names they had under OS/2 13.) Figure 4 
shows a printer-properties dialogue with fields 
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that pertain to the specific capabilities of a 
particular printer model 

Device (Printer) Font Installation 

Printer properties include a dialogue for 
installing device fonts, including extended font 
character sets and patterns. Today's lay and 
commercial public has some savvy concerning 
the influence of fonts in calling attention to 
documents. Consult Perks' article or the OS/2 
Programming Guide section "Font Dialog and 
Device Font Considerations" to find how your 
program uses logical fonts. If you use logical 
fonts from CPI APIs within your program, your 
user can change font selection from the shell 
without having to also adjust a document. 

Job-property Defaults 

Each printer object has defaults for such per- 
job characteristics as orientation, resolution, 
form selection, and one- or two-sided printing. 
Default job properties provide the per-job 
setup your application queries (with 
DevPostfteviceModes) and displays, then invite the 
user to change them. The Printer driver 
settings page has a Job properties button 
control for accessing these default settings. 

Queue Options 

This settings page, shown in Figure 5, provides 
a way to change queue drivers or to specify 
PM JJ.RAV data type. 

Queue Processor (or Driver) 

Most printers and plotters use the standard 
PMPRINT software queue driver, but the pop-up 
menu for PMPRINT has an option for installing a 
different one. Selecting the added driver in the 
Queue driver field activates it. 


OS/2 Programming Guide. The system 
automatically converts a PM_STD file to 
PM_Q_RAW, when required by the printer-object 
setup, freeing your application from the 
necessity to indicate a data type. 



Figure 4: Printer properties dialogue 



Figure 5: Settings notebook page 


PM_Q_/?AIV (Printer-specific Format) 

If a printer object has a check mark in the 
Printer-specific format field, all its queued 
spool files contain PM_Q_RAW data or printer- 
specific control characters. By contrast, the 
more concise metafile format (or PM_Q_STD data 
type) holds a description of job setup that 
needs further interpretation by the printer 
driver. The selection for this field is indicated 
internally as data type (PRQINF03 sfType), as 
explained in detail in Perks' article and the 


Job Dialogue Before Print 

A user can also request to have the job- 
properties dialogue displayed for modification 
each time a print request involves this 
particular printer object The dialogue does not 
appear in conjunction with a job printed from 
your application and does not affect jobs 
created by your application, it is provided for 
people who print directly on the desktop, 
using the drag-and-drop method. 





























































IBM OS/2 Developer 



THE DEFAULT SYSTEM PRINTER 

In the past, a Print Manager™ menu option 
called Application default was used to change 
the queue, serving as the system default. Every 
OS/2 2.0 printer object's menu has an option 
called Set default that performs the same 
function. Despite its former name, this default 
has little influence on your application. It 
specifies the device for output generated by 
pressing the Print Screen key or by selecting a 
button to print a Help topic. 



Figure 6: Submission-data settings 


Spooler Options 

Path opens the Spooler object to see this sole 
setting, provided as a performance 
enhancement. If you write an application that 
relies on large PM_Q_RAW queue files or one with 
which you expect your customer to create a 
large volume of simultaneously queued jobs, 
suggest in your documentation that the 
customer change the path in this field, perhaps 
to a separate disk. 

Direct printing indicates that there is no means 
to set up a printer object for direct printing. To 


print without queuing, your user can disable 
the spooler for the entire system. If you use an 
QD_DIRECT device context, you (and your 
customer) forfeit all these nice setup 
opportunities provided with the printer object. 
You also take away your user's opportunity to 
manage a job from the open printer-object 
window. And, of course, you foil the 
efficiencies of spooling by tying up the printer 
with your direct-output job. 


JOB MANAGEMENT 

You guessed it, jobs are objects. The user can 
directly manipulate them or select menu 
options for them. Once the spooler assigns the 
job to its printer object, opening the printer 
object to its default icon view displays a 
window' where the pending job icons live. In 
reality, these jobs rarely stay on the queue long 
enough for anyone to inquire about or alter 
them. If you want to check the state and setup 
for job objects while testing your application, 
use the pop-menu of the printer object, the 
Change status option, to hold the printer object. 

With the job-object menu and settings, any 
shell user can alter printing order or job 
priority; copy, delete, or hold and release jobs; 
and even override area and fit. Double-click on 
a job to view its content; press the second 
mouse button to display a pop-up menu from 
w hich you can open to the settings view. As 
application developer, you will find the 
settings pages of a job indicate how well your 
application accomplished its job-submission 
setup. Each tabbed page of the job settings has 
a Help button, in case you do not find the 
fields self-explanatory. 

Perks' article and the OS/2 Programming Guide 
tell you how r to display job-properties defaults 
to give your user an opportunity to override 
them for a single job. To ascertain whether 
your software correctly spooled the 
overridden properties, double-click on the 
printer-driver icon shown in the upper right of 
the job's Submission-data settings, shown in 
Figure 6. In this context, the printer-driver 
settings pertain to job properties, not printer 
properties. 
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RESOURCES 

About the Interface 

Two on-line procedural guides have a 
separate icon directly on the desktop: 

1, Start Here topics installing printers 
and printing. 

2. The Master Help Index topics 
printing, queue, port, and spooler. 

Consulting Start Here and the Master 
Help Index gives you, the developer, a 
feel for your users' expectations 
concerning printing. 

About Programming to the Interface 

These references cover the graphics 
interface and printing. Use them not only 
for issuing your print job, but also for 
determining which APIs you need to 
ensure the appropriate font and graphic 
transformations: 

"Chapter 18: Print job Submission and 
Manipulation/' The OS/2 Programming 
Guide Volume III: Graphic Programming 
Interface. 

Presentation Manager Programming 
Reference Volume III (available on line). 

Developer's Toolkit for OS/2 2.0, sample 
program PRINT. 

Perks, Michael. "Application Printing 
using OS/2 2.0/' IBM OS/2 Developer 
(Summer 1992): 42*51. 

Reich, David E, "Programming Printing 
Under OS/2/' Personal Systems Developer 
(Winter 1992): 85-95. 


TIPS AND MISCELLANY 

•■'/oV'MiiVi 

• ' I t , X' 

* Port timeout. Jf you anticipate PostScript printing, advise your 
customer to set a minimum of 120 seconds as the timeout period to 
prevent frequent off-line messages. 

* Reverse clipping. If your drafting software has no option to hide the 
background lines of solids, advise your customer to install the 
PMPLOT.DRV printer driver and PMPLOT.QPR queue driver, both 
of which are supplied with OS/2 2.0. The user can retain a separate 
printer object with these two selected. This printer object must have 
the plotter driver for the model and PMPLOT.DRV selected in the 
Default printer driver settings field. For more details about reverse 
dipping, select the topic "plotter, reverse clipping considerations" 
from the on-line Master Help Index, 

* Network printing. Device-independent (PH_QJ>TD) metafiles are 
smaller than printer-specific format (PfU)_RAy) files by a factor of five. 
Obviously, the smaller metafile will travel over the network more 
efficiently. If a network server supports OS/2 printer drivers, the 
system automatically gives your customer optimum performance by 
using the standard data type. If the network does not support PM 
metafiles, the local OS/2 seamlessly converts your print-job stream to 
specific (RAW) format required by the network printer. For the network 
printing data structures, see the OS/2 Programming Guide section 
"Network Printing Considerations/' For more information about 32- 
bit network independent APIs, search your on-line Presentation 
Manager Programming Reference. 

* Direct printing* If you must bypass the spooler, you can obtain the 
names of physical devices by requesting from SplEnumQueue, flType 
SPL_PfCQUEUED_DEVICE. This flType lists the physical devices associated 
with printer objects and identifies them by their logical names, such 
as "Printer 1". Do not request flType SPL_POIRECT_DEVICE, which in 
OS/2 1.3 returned devices that have no associated queues. The OS/2 
2.0 shell does not permit the user to define a nonqueued print device. 
It is not recommended that your application define one, either. 

It is also possible to print directly to the spooler with a PM_Q_RAW job. In 
the OS/2 Programming Guide, see "Submitting a Direct Presentation 
Manager Print Job" and "Submitting a Print job Directly to the Spooler" 
for details. 
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32-Bit OS/2 

DOS Application Printing: 
Understanding the Differences 
Under OS/2 


by Frank f Schroeder 

Mam/ DOS applications can send information to a 
printer; they implement this feature through a 
variety of different interfaces, OS/2 provides 
support for these interfaces, allowing DOS 
applications to print when miming under OS/2. 
When printing* DOS applications sometimes 
behave differently under OS/2 than when running 
under DOS . This article describes the interfaces 
DOS applications use to send data to a printer, 
some of the differences encountered when printing 
under OS/2 , and changes made to OS/2 during 
development that enable DOS applications to print. 
Some of these changes resulted in options that can 
be customized to an application. This article will 
show you how to recognize these differences, apply 
Us recommendations, mid gain an appreciation of 
what has been implemented in OS/2 to maintain 
DOS compatibility and provide an OS/2 version 
able to stand up to the claims of being "a better 
DOS than DOST 

INTRODUCTION 

B efore describing these behavioral 

differences and recommendations, this 
article presents a review of how printing is 
accomplished from DOS applications. With 
this knowledge, it is easier to see behavioral 
differences between DOS and OS/2 as well as 
how new features in OS/2 2,0 allow a DOS 
application to print. Some of these new 
features require tailoring by the user; a proper 
setting for one DOS application may be 
improper for the next. 

DOS applications send information to be 
printed using several software interfaces. 

They are: 


• Direct manipulation of parallel port 
hardware 

• BIOS Interrupt 17h 

• DOS Interrupt 21 h. 

The two most popular interfaces for printing 
are DOS interrupt 21 h and BIOS interrupt 17h. 

DIRECT ACCESS TO 
PARALLEL PORT HARDWARE 

I do not recommend the direct access to 
hardware printing approach, as it limits an 
operating system's ability to coordinate 
application access to hardware. Problems 
found in hardware can be worked around by 
operating system software. Well-written 
applications are hardware independent; 
applications should not require change as 
hardware changes. Very few DOS applications 
interface directly to the parallel port hardware 
to print, as shown in Figure 1. 

Intermixed printer output occurs in OS/2 1.x if 
an OS/2 application is printing in the 
background and a DOS application is printing 
in the foreground by direct access to hardware. 
The Intel 80286 processor cannot provide port 
trapping, which would prevent intermixed 
output, as shown in Figure 2. 

Any DOS application accessing the parallel 
ports directly in OS/2 2.0 is trapped by the 
virtual parallel port device driver (VLPT). 
VLPT asks the physical parallel port device 
driver if the DOS application may access the 
hardware directly, through the inter-device 
Driver Communication (IDC). If permission is 
granted, the DOS application is allowed 
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Figure 1: DOS 5.0 printer subsystem 


exclusive use of the parallel port hardware 
until it terminates. Printing from other OS/2 
applications can continue to spool but will not 
be permitted to print until exclusive access is 
released, as shown in Figure 3. 

Most DOS applications do not access 
hardware directly. For those that do, OS/2 2.0 
coordinates this access with other parallel port 
hardware accesses to prevent intermixed 
output. 

BIOS INTERRUPT 17H 

Basic Input/Output System (BIOS) is a set of 
functions in ROM that perform low-level 
interfacing with the hardware. DOS uses BIOS 
interrupt 17h to send data to printers attached 
to parallel ports, as shown in Figure 1. If a 
DOS application issues interrupt 21 h functions 
G5h or 40h, they are converted by DOS into 
BIOS interrupt 17h requests. 

In OS/2 Lx versions, there is only one DOS 
session. The physical parallel port device 
driver intercepts all requests to interrupt 17h 
and coordinates DOS application printing with 


printing by other applications, as shown in 
Figure 2. A disabled spooler in OS/2 can result 
in intermixed printer output, 

OS/2 2.0 allows up to 240 DOS sessions. A 
new component, the virtual device driver, 
keeps track of DOS applications as they 
attempt to manipulate hardware or issue BIOS 
interrupt calls. VLPT handles DOS application 
accesses to interrupt 17h, buffering these single 
character requests and passing buffers through 
the OS/2 kernel to the parallel port device 
driver for printing, as shown in Figure 3. 

Most DOS applications print to interrupt 17h 
instead of interrupt 21 h. Interrupt 17h is a very 
simple interface which performs better 
because it is specific for printing and does not 
require involvement by the DOS operating 
system. In any case, the DOS operating system 
passes interrupt 21 h print requests to BIOS 
interrupt 17h. Developers, in an attempt to 
achieve better performance, have chosen to 
bypass interrupt 21 h and code directly to 
interrupt 17h. The design of interrupt 17h, 
which does not include open or close requests 
to bracket the print request, has led to spooling 
problems. These issues had to be overcome so 
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Figure 2: DOS application printing in OS/2 Lx 


Most of the 
different 
behaviors occur 
in the 
interaction 
between DOS 
applications 
and the OS/2 
spooler. 
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these DOS applications could print in a DOS 
session. 

DOS INTERRUPT 21H 

DOS applications pass information to the 
operating system to be printed using Function 
Q5h (Printer Output) or Function 40h (Write to 
File or Device) of the DOS interrupt 21 h 
interface, 

DOS utilizes standard handles, devices opened 
by the operating system and available without 
an explicit open request. Similarly, when an 
application is ready to terminate, it need not 
issue an explicit close request. One of the five 
DOS standard handles corresponds to the the 
standard printer, the first parallel port in a 
system. 

When a DOS application is started, the 
operating system generates an open request on 
behalf of the application. After receiving a 
print request from the user, the application can 
issue multiple interrupt 21 h function 05h 
requests to send data, character by character, 
to the printer. When the application 
terminates, the operating system generates the 
corresponding request to close the data stream. 

Interrupt 21 h function 40h works a little 
differently. The DOS application must first 


issue an explicit open request (function 3Dh) to 
open the data stream before issuing the 
function 40h, which sends data to the printer. 
This process gives the application more control 
over which system resources it uses (e.g., file 
system handles) and when it uses them. Once 
the DOS application has completed 
transmitting the data to be printed, it must 
issue an explicit close request (function 3Eh) to 
dose the data stream. 

In OS/2, interrupt 21 h requests are converted 
by the DOS kernel into OS/2 kernel requests, 
which are then passed to the parallel port 
device driver for processing, as shown in 
Figures 2 and 3. Some DOS applications use 
interrupt 21 h function 40h to print; a few of the 
older ones use interrupt 21 h function G5h. 
Subtle differences in how DOS applications are 
coded to perform the printing function can 
have dramatic effects in the multitasking 
environment of OS/2 when the spooler is 
enabled. 


DOS APPLICATION 
PRINTING DIFFERENCES 

. I,,, v/T 

With an understanding of the various printing 
methods DOS applications use and how DOS 
avid.06’/ 2 handle these methods, we can now 
begin, to understand some of the different DOS 
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Figure 3; DOS application printing hi OS/2 2.0 



application printing behaviors users may 
encounter. Most users do not know or care 
which method DOS applications use to print. 
They are interested in hard-copy output; if that 
output isn't printed properly and quickly, 
users are upset—and rightly so. 

One significant difference between DOS and 
OS/2 is their single-tasking versus 
multitasking capabilities. With a single-tasking 
operating system such as DOS, the task has 
ownership of all devices and can access them 
at will OS/2 must control multiple tasks 
attempting to access the same hardware and 
must prevent collisions that cause applications 
to hang or produce other unexpected errors. 
The OS/2 spooler handles printer device 
contention. If it is disabled, multiple 
applications attempting to print 
simultaneously can cause intermixed output. 

These are some of the differences encountered 
when DOS applications attempt to print from 
within a DOS session of OS/2: 

* Instantaneous printing 

* BIOS Interrupt 17h printing 

* Interrupt 17h Terminate-and-Stay Resident 
(TSR) DOS programs 


• Open and close requests with no write 
request (ghost jobs) 

• Open request at initialization and close 
request at termination 

• Open and close request for each application 
buffer printed 

• DOS applications accessing hardware 
directly. 

The next section contains a description of each 
difference followed by some insight into 
changes made to OS/2 that allow DOS 
applications to print. Interacting with the 
spooler does not necessarily correspond to 
how DOS applications print. Most different 
behaviors occur in the interaction between 
DOS applications and the OS/2 spooler, 

INSTANTANEOUS PRINTING 

Behavioral Difference 

One of the first things a user notices when 
printing from a DOS application under OS/2 
is that the printer does not begin printing as 
quickly as when running the same application 
under DOS. This slower response time 
sometimes translates into a negative 
perception of OS/2, 
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Recommendation 

One important difference between DOS and 
OS/2 is the inclusion of a printer spooler. 
(Compare Figure 1 to Figures 2 and 3.) If the 
spooler is enabled, the entire print job is sent 
by the DOS application to the spooler, which 
must write it to a temporary spool file before it 
can be sent to the printer. The spooler must 
behave this way because it is managing 
serially reusable devices and cannot assign a 
printer to an application while the application 
is busy building the file to print. The spooler 
tries to achieve maximum utilization of the 
devices it manages; another application may 
have a small job to print, but cannot do so if 
the spooler assigned the device to the first 
application, even if the first application leaves 
the printer idle while building the output. 



SiaitHere Templates 



Window Viewer 


l w l 


e 




Shieddei Master Help Irtdex Inlttmabon lift warm IBM 4207PropfiniefX24 



■ I 






Figure 4: OS/2 2,0 Print while spooling queue option 


The spooler is necessary in OS/2 unless the 
user performs the serialization of accesses to 
the printer. The spooler can be disabled if a 
user wants to print from only one application 
at a time; in this case, printing begins 
instantaneously. 

In OS/2 1.x, spooler design was based on the 
character monitor mechanism. In OS/2 2.0, it 
has been redesigned as an installable file 
system, which improves performance. The 


monitor dispatcher has been rewritten using 
32-bit instructions, and the parallel port device 
driver monitor interface has been made wider, 
improving character monitor throughput and 
reducing the amount of time before printing 
begins. 

In OS/2 2.0, a new queue option allows 
printing to commence before spooling is 
completed, as shown in Figure 4. By selecting 
the Print while spooling checkbox, the user 
can toggle this option on (default) or off. Print 
while spooling saves time by starting large 
print files before the entire file has spooled. A 
side effect may occur with certain applications. 
If an application does not issue a close printer 
request after sending data to print, the next job 
in the queue cannot begin printing until the 
dose request is received. Users may need to 
take overt action, such as pressing a special 
key sequence (Ctrl-Alt-Print Screen in the DOS 
session) or terminating the application to 
generate the close. The Print while spooling 
option is not recommended on print servers. 


BIOS INTERRUPT 17H PRINTING 

Behavioral Difference 

A unique characteristic interrupt 21 h has over 
BIOS interrupt 17h is the ability to identify the 
beginning and end of the data stream. Each 
data stream corresponds to one print request 
and one spool file. When the physical parallel 
port device driver in OS/2 1.x or the virtual 
parallel port device driver in OS/2 2.0 sees the 
first interrupt 17h print request in a DOS 
session, it recognizes the start of the data 
stream and informs the spooler to open a spool 
file. Interrupt 17h print requests can be 
buffered in the device driver until the buffer 
becomes full, at which time the buffer can be 
written into the spool file. Of primary concern 
is how the device driver can detect the end of 
the print request so that the data stream can be 
dosed and the spooler can send the request to 
be printed. In this case, the user sees that the 
DOS application has "printed/' but no hard 
copy has been generated. 

Recommendation 

Several methods have been built into OS/2 to 
start interrupt 17h initiated print requests: 
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* Application termination 

* DOS session termination 

* Ctrl-Alt-Print Screen key sequence 

* DOS Timeout (05/2 13) or PRINT_TIME□ UT 
DOS Setting (OS/2 2,0) 

Users notice the most obvious method when 
they terminate the DOS application and the job 
starts printing. The device driver receives 
notification of application termination, writes 
any remaining characters in its buffer to the 
spooler, and closes the spool file. In OS/2 2,0, 
termination of the DOS session generates the 
same behavior as terminating the application. 

The key sequence Ctrl-Alt-Print Screen, added 
in OS/21.x, causes any remaining data to be 
written and the spool file closed. This 
approach requires that the user knows the key 
sequence, performs the sequence once the DOS 
application has finished sending the print job, 
and presses the keys at the appropriate time, 
since doing so prematurely splits the print job 
into two spool files. With this option, the user 
stii! has to perform an action that is not 
necessary when printing from the same 
application under DOS. 

A more transparent method called DOS 
Timeout was added to the OS/2 1.3 Print 
Manager setup menu to automatically flush 
the final buffer and close the spool file when 
interrupt 17h print requests stop occurring. 

The DOS setting option PRINTJTME0HT in OS/2 
2,0 performs the same function, as shown in 
Figures 5 and 6. 

Following is an example of a setting that must 
be tailored to the application. Some DOS 
applications issue interrupt 17h requests to 
print and generate only some of the print data 
before issuing more requests and repeating the 
process. If a DOS application prints in spurts 
and a very small timeout value is specified, the 
timeout may expire when the application is 
generating more print data. The print job may 
then be split into two spool files. Conversely, if 
the user specifies an inordinately large timeout 
value, he or she may wait unnecessarily before 
the final buffer is sent to the spooler, the spool 
file is dosed, and the job begins to print. 
(Subtleties like these exist even between DOS 


applications using the same interface to print) 

Once the end of a data stream is determined, 
the start of the next job can be determined and 
the process can repeat itself for the next print 
job within that DOS session. 



INTERRUPT 17H TERMINATE- 
AND-STAY RESIDENT (TSR) 

DOS PROGRAMS 

Behavioral Difference 

Since DOS maps interrupt 21 h print requests 
to interrupt 17h, DOS application developers 
have developed TSR applications that replace 
the BIOS interrupt 17h routine in the interrupt 
vector table with an entry point into their TSR 
application. When print requests occur, the 
TSR gains control and performs its operation 
before printing by directly accessing the 
parallel port hardware or passing the request 
on to the BIOS interrupt 17h routine. The user 
wonders why the DOS application (TSR) 
doesn't see print requests under OS/2. 


Some settings 
need to be 
tailored to the 
application. 
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Figure 5: DOS timeout option in OS/2 13 


Recommendation 

When a DOS application issues interrupt 21 h 
print reLjuests in OS/2, the DOS kernel 
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FigureS: PRIHT.THEQUT DOS netting in OS/2 2.0 


receives control and sends buffers to the 
parallel port device driver to print instead of 
converting them to interrupt 17h requests, as 
under DOS. Tills 05/2 performance 
enhancement prevents DOS TSRs from being 
able to perform their function. 

OS/2 2.0 has shipped a DOS device driver 
called LPTDD.SYS which converts interrupt 
21 h requests to interrupt 17h requests so the 
TSR class of DOS applications will work 
properly. This device driver is installed into 
the \Q52\MDOS subdirectory but is not 
loaded by default. 

A user can load the DOS device driver using 
the DEVKE=C:\0S2\-HD05\LPTOD. SYS statement in 
config.sys so it applies to all DOS sessions or 
add C:\0S2\MD0S\LPTDD.SYS to the DOS_DEVICE DOS 
setting so it applies to one particular DOS 
session, as shown in Figure 7, 


OPEN AND CLOSE REQUESTS 
WITH NO WRITE REQUEST 

Behavioral Difference 

When DOS applications are loaded to run, 
OS/2, like DOS, opens the standard printer 
handle. WTien DOS applications terminate, 
OS/2 closes this handle. The spooler generates 
a temporary spool file when it receives a 
printer open request and closes the file with a 
corresponding dose request. In beta testing, if 
a user looked at the spool queue (in the Print 
Manager of OS/2 1.x or the Print Object of 
OS/2 2.0), a job used to appear and then 
disappear but nothing was printed. This 
behavior gave the impression of a lost spooler 
output file, commonly dubbed a "ghost file," 
when, in reality, nothing was ever printed by 
the application using DOS interrupt 21h 
function Q5h. 

A similar problem occurred if code page 
switching was enabled or the form-feed 
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Figure 7; MS .DEVICE DOS setting in OS/2 2,0 


control was set within the printer properties 
dialogue of the printer driver. If the form-feed 
option was activated, a blank sheet of paper 
passed through the printer. 

Recommendation 

In this case, the spooler was modified so it 
would not alert the spool queue of the print 
job until data was received and written to a 
spool file. This hid the open and close requests. 
The spooler was optimized to discard empty 
spool files or files that contained only printer 
code page downloads, so users should no 
longer see ghost files in the spool queue, 

OPEN REQUEST AT 
INITIALIZATION AND CLOSE 
REQUEST AT TERMINATION 


when the application does its initialization 
code and close it using interrupt 21 h function 
3Eh at termination processing. If a user 
requests printer output from within a DOS 
application written with this algorithm, the 
print job is spooled but remains in the 
"spooling" state, as the application doesn't 
close the handle until it is terminated. The 
spooler needs to receive the close request as a 
signal that the application is finished sending 
data to the printer so printing can commence. 

Recommendation 

The DOS device driver LPTDD.SYS can 
convert interrupt 21 h print requests into 
interrupt 17h print requests. One of the 
methods described under BIOS Interrupt 17 
Printing can be used to close the spool file. The 
spooler will then automatically initiate 
printing. 


i 


Behavioral Difference 

Some DOS applications open a file handle to 
the printer using interrupt 21 h function 3Dh 
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OPEN AND CLOSE REQUEST FOR 
EACH APPLICATION BUFFER 
PRINTED 

Behavioral Difference 

A few DOS applications open and dose the 
printer handle using interrupt 21 h function 
3Dh and 3Eh for each buffer of a print job 
being sent to a printer. Although this behavior 
is not a problem in DOS, under OS/2 it causes 
multiple spool files to be generated for one 
print job. If a user holds the spool queue and 
prints with an application written this way, 
many files appear in the spool queue and give 
the impression that he or she has requested 
that the DOS application print the job once for 
each spool file in the queue* In reality, only one 
job is in the queue but it has been split into 
many pieces. 

Recommendation 

This is usually not a concern; however, it does 
dutter up the spool queue and add 
unnecessary overhead to the system. OS/2 has 
not done any work to detect this situation or 
collapse these files into one spool file, as this 
problem has not been widespread* The Browse 
Spool File option in OS/2 2*0 will not provide 
the desired results, as only partial output can 
be viewed. 

DOS APPLICATIONS ACCESSING 
HARDWARE DIRECTLY 

Behavioral Difference 

An operating system can do little to prevent 
DOS applications running under DOS or OS/2 
Lx from directly accessing PC hardware. An 
application that directly manipulates 
hardware can compromise system integrity, 
especially if the hardware is left in an altered 
state. 

A user may find that one DOS program 
printed, but print jobs now spool but won't 
print* The LPTx queue appears hung, the 
printer is ready, and other queues print with 
no problems. The user cannot detect what 
could be wrong. 


Recommendation 

Using the port-trapping feature of the Intel 
80386 and 80486 processors, the virtual parallel 
port device driver of OS/2 2.0 traps the 
attempts to manipulate the parallel port 
hardware and coordinates this hardware 
access with the operating system's hardware 
access* When a DOS application terminates, 
exclusive control is returned to the operating 
system, and the port is reset to its default state. 

There is a limitation when DOS applications in 
OS/2 access hardware directly. While the DOS 
application is touching the hardware, no other 
applications, including other instances of the 
same application, can touch the same 
hardware. The spooler is prevented from 
printing by the parallel port device driver until 
the DOS application terminates. Several classes 
of DOS applications fit into this category, 
including file transfer programs and software 
security devices attached to the parallel port* 

CONCLUSION 

This article has described the methods DOS 
applications use to print, how OS/2 tries to 
accommodate these applications, and some 
customization available in OS/2 that enable 
DOS applications to peacefully coexist with 
OS/2 and Windows applications. This article 
has also explained some of the behind the 
scenes architectural decisions that enable DOS 
applications to perform better under OS/2* 

Frank J. Schroeder, IBM Entry Systems 
Division, 7 000 N* W. 51st Street , Boca Raton , Fla. 
33429. Schroeder is a staff programmer in the OS/2 
Deince Drivers and MVDM department. He joined 
IBM in 1984 and is currently toothing on 
performance and functional enhancements to the 
OS/2 Printer Subsystem. He holds a B.T< in 
computer science from Rochester Institute of 
Technology in New York , and an AT 8.A. in 
business administration from the University of 
Miami , Florida. 
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32-Bit OS/2 

Class Objects in SOM 



by Nurcan Coskit n and Roger Sessions 

This article continues the discussion of SOM that 
began in the Winter 1992 issue of IBM Personal 
Systems Developer. This article examines the 
class object, an advanced programming feature of 
SOM. At run time , a class object can retrieve 
information about a class , such as the class name 
and supported methods, and can also instantiate 
objects of a given class. We will give an overview of 
class objects and discuss metaclass, or the class of a 
class object. We will also demonstrate two 
techniques for changing a metaclass. 


object-oriented programming, such as 
developing classes and instantiating objects, 
deriving new classes through inheritance, and 
resolving methods with polymorphism. We 
also covered the primary goals of SOM: 
multilanguage support for procedural and 
object-oriented languages, upwardly 
compatible binaries, and object-oriented 
extensions to non-object-oriented languages* 

With our previous article as a base, this article 
will explore class objects in SOM, For full 
information on using SOM, see the SOM guide 
and reference (IBM, SOM, 1992). 



Roger Sessions 


INTRODUCTION 


I n our last article (Sessions and Coskun 1992, 
107-119), we gave a general introduction to 
the System Object Model, or SOM. Introduced 
by IBM with OS/2 2.0, SOM is a new 
methodology for creating object-oriented class 
libraries. We discussed the basic concepts of 


GOALS OF SOM 

SOM is a language-neutral mechanism for 
developing object-oriented class libraries, 
consisting of a run-time repository for class 
information and a series of language bindings. 
SOM's structure is diagrammed in Figure 1. 
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Figure I. Pictorial representation of the System Object Modet (SOM) 
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The box in Figure 1 with C pointing to the 
Run-Time Repository represents a binding that 
allows classes to be defined in C and added to 
the SOM run-time repository. The connection 
between the run-time repository and C is a 
binding that allows C to use classes from the 
repository regardless of original language. 
"Using a class" means either instantiating and 
invoking methods on objects of a particular 
class or deriving new classes using that class as 
a base. 

OS/2 2,0 currently supports only C bindings; 
other languages in Figure 1 are for illustration 
only. While we are working with a wide 
variety of language suppliers to increase the 
number of supported languages, this is neither 
a complete nor committed list of languages 
under consideration. 

As we discussed in our first article, C bindings 
allow object-oriented programs to be 
developed much as they are in C++, with the 
difference that classes in SOM can be used by a 
variety of languages as new language bindings 
become available, SOM improves on other 
class library weaknesses in C++; for an 
introduction to C++ and library issues, see 
Class Construction in Cand C++ (Sessions 1992), 

CLASSES IN SOM 

Let's consider a set of classes we first looked at 
in the Winter issue, starting with the Student 
class. An object of type Student knows how to 
set up its ID and name, how to return its ID, 
and how to print itself The class definition file 
for Student is shown in Figure 2. 

Figure 3 shows the class implementation file 
for Student* Most of this file is produced 
automatically by the SOM compiler; the lines 
the class implementor needs to write are 
shown in bold face. 

Given the definition of Student, we can derive a 
new class called GraduateStudent, which has 
additional information on thesis and degree. 
The class definition file for GraduateStudent is 
shown in Figure 4, and the class 
implementation file is shown in Figure 5. 

With these two classes defined and 
implemented, we can write client code to 
instantiate and manipulate Students and 


include <somobj.sc> 
class: 

Student; 

parent: 

SOHObject; 

data: 

char id[16]; /* student id */ 

char name[32]; /* student name */ 

methods: 

override somlnit; 

void setUpStudent{char *id, char *name); 
void printStudentlnfo(); 
char *getStudentType{); 
char *getStudentId{); 


Figure 2: Student class definition 

GraduateStudents, The program in Figure 6 
instantiates two Students and two 
GraduateStudents, initializes the objects with 
data, and asks the objects to print themselves. 

CLASS OBJECTS 

Every class with at least one instantiated object 
has exactly one associated class object. Each 
instantiated object maintains a pointer to its 
class object, which it can return via somGetClass. 
This method is inherited from SGMObject, a class 
from which every class is derived either 
directly or indirectly. In the program in Figure 
6, student 1 and student2 are both objects of class 
Student, and therefore both share the same class 
object Similarly, gradi and grad2 are both 
objects of class GraduateStudent and share a 
second, different class object. The relationship 
between objects and their class object is shown 
in Figure 7. 

Another way to access a class object is through 
the SOM defined macro .cLassObj, which 
returns a pointer to the appropriate class 
object, or to zero if none exists* For Student, the 
macro is .Student. SOM instantiates a class 
object the first time an object of its controlled 
class is instantiated* The .Student will therefore 
return 0 if and only if no Student objects have 
yet been instantiated. 

The class object can tell you many things about 
a class, including its size, its parent, whether it 
is derived from some other class, and whether 
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tdefine Student.Qass.Source 
Jtindude 11 student, ill M 

void somlnitfStudent *somSelf) 

{ 

StudentData *somThi$ = StudentGetData(somSelf); 
parent^somInit(somSeIf); 

_id[G] * _name[0] - *\0'; 

} 

void setUpStudent($tudent ♦somSelf, 
char *id, char *name) 

{ 

StudentData tsofnlhis = StudentGetData{som$elf); 

strepy(_id, id); 
strepy(.name , name); 

} 

void printStudentInfo{Student *sorn5elf) 

{ 

StudentData *$omThis ^ StudentGetData(scmSelf); 

printf( fl \n Id : Xs \n\ _id); 

printft" Name : Xs \n", .name); 

printf(" Type : Xs V, _getStudentType(somSelf)); 

> 

char * getStudentType{Student *somSelf) 

{ 

StudentData *somThis = StudentGetData(somSelf); 

static char *type = "student 1 *; 
return (type); 

} 

char * getStudentId(Student fcsomSelf) 

{ 

StudentData *somThis = StudentGetData(sornSelf); 

return (_id); 

} 


FigureS : Student implementation (programmer added tines shown in boldface) 


it supports a specific method. The class of a 
class object is either SOMClass or some class 
derived from it. A variety of methods defined 
for SOHClass are documented in the class 
definition file for SQMClass, somcls . se, and the 
SOM documentation. 

One SQMClass method is somGetNameO, which 
returns a pointer to a character string 
containing the name of the class for which you 
have indicated the class object. For the Student 
class object this string would be "Student/ 1 

Another interesting SOMClass method is 
somNeuO, which returns a newly instantiated 


object of the appropriate class. For the Student 
class object, it would return a newly 
instantiated object of the Student class. 
Although somftleyQ is always invoked to 
instantiate new objects, many programmers 
are unaware of this because they use a macro 
wrapper of the form classnameNe* (for example, 
StudentNewO). The wrapper first makes sure the 
appropriate class object exists and then makes 
the instantiation request via somNey(). 

In most cases, we would instantiate objects 
using the class instantiation macro, as with 
StudentNevQ. There are some cases, however, in 
which the class object but not the class 
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include "student.sc“ 


class: 


GraduateStudent; 


parent: 


Student, local; 


data: 


char thesis[128]; 

/* thesis title */ 

char degree[16]; 

/* graduate degree type */ 

methods: 


override somlnit; 


override printStudentlrofo; 

override getStudentType; 

void setUpGraduateStudent(char *id, char *naroe, 


Figure 4: GraduateStudent class definition file 


instantiation macro must be accessed, such as 
a function that accepts a pointer to any object 
and returns another newly instantiated object 
of the same class. Figure 8 modifies the 
program in Figure 6 to make use of the Student 
and GraduateStudent class objects and the 
somGetCLassO and somNewQ methods. 

Several of the SOHClass methods have 
passthrough methods defined in SOMObject. In 
these cases, the code for the passthrough 
methods simply gets the object's class object 
and passes through the call using the 
appropriate SOHClass method. For example, the 
SOMObject method somGetCLassNameO passes 
through to the SOHClass method somGetNameO. 
This article uses either the SOHClass methods or 
the SOMQbject passthrough, depending on the 
point to be made. 

THE CLASS OF THE 
CLASS OBJECT 

Every object in SOM is associated with a class. 
The class of student is Student; 

tinclude "student.h" 

mainQ 

{ 

Student ^student = StudentNewQ; 
printf ("student object is of <7*s> class\n", 
_somGetClassName(student)); 

> 

which gives the output: 


student object is of <Student> class 

Class objects are also associated with a class. 
Because SQHQass is, like all classes, derived 
from SOMObject, it therefore supports all 
SDHObject methods. We can, for example, verify 
the class of the Student class object; 

tfinclude “student.h" 

main() 

{ 

Student ^student = StudentNewQ; 

SOHClass *studentClassQbject; 

studentClassGbject - _somGetClass(student); 
printf ("student object is of <7*s> class\n", 
_somGetClassMarne(studentQassQbject)); 

> 

giving the output: 

student class object is of <SQHClass> class 

We use "metaclass" to describe the class of a 
class object. For example, the class of the 
student's class object is SOHClass; thus the 
metaclass of Student is SOHClass. Class and 
metaclass should not be confused; the class of 
student is Student, while the metaclass of student 
is SOHClass. 

We can change the metaclass of a given class 
by a two stage process: 

* Derive a new class from SOHClass, either 
directly or indirectly 
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#define GraduateStudent_Class_$ou rce 
linclude "graduate, ill" 

void sorrTniU GraduateStudent *sonSelf) 

{ 

GraduateStudentData *sornThis = 
GraduateStudentGetData(somSelf); 
parent_somInit{sornSelf); 

_thesis[0] 3 _degree[0] ■ '\0'; 

> 

void printStudentInfo( 

GraduateStudent *somSelf) 

{ 

GraduateStudentData *somThis 3 
GraduateStudentGetDatatsomSelf); 
parent_printStodentInfG(somSelf); 
printf( n Thesis : Jis \n", .thesis); 

printfC 1 Degree : Xs \n‘\ .degree); 

} 

char * get$tudentType( 

GraduateStudent *somSelf) 

{ 

GraduateStudentData *somThis = 
GraduateStudentGetData(somSelf); 

static char *type = "Graduate"; 
return (type); 

} 

void setUpGraduateStudent( 

GraduateStudent *somSelf f char *id, char ♦name, 
char *thesis, char ^degree) 

{ 

GraduateStudentData *somThis = 
GraduateStudentGetData(somSelf); 

_setUpStudent(somSelf ,id, name); 
strcpy(.thesis, thesis); 
strcpy(.degree, degree); 

} 


Figure 5: GraduateStudent class implementation file (programmer added lines shown in boldface) 


* Use the metaclass directive to tell the class of 
its new class object. 

There are at least three reasons to change the 

class of a class object: 

* To add methods for initializing new objects 
(constructor methods) 

* To modify how memory is allocated for 
objects 

* To keep track of global information about 
the class, such as the number of instantiated 
objects. 


Lets go through the steps necessary to change 
the metaclass of student from SOMClass to 
Student Factory (in other words, to change the 
the class of the Student class object from 
SOMClass to StudentFactory). Let's say we want 
StudentFactory to keep count of the number of 
instantiated students, functionality not 
provided by the standard SOM class. The steps 
are: 

* Define StudentFactory to be derived from 
SOMClass. This adds one new method, 
countObjectsO, to StudentFactory. 
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Program: 

#inciude "graduate.h" 

rnainO 

{ 

Student *studenti = StudentNewQ; 

Student *student2 = StudentNewQ; 

GraduateStudent *gradl = GraduateStudentNewO ; 
GraduateStudent *grad2 = GraduateStudentNewO; 

_setUpStudent(student!,"120455","Joe Doe"); 
_setUpStudent(student2,"103606","Mary Smith"}; 
_setUpGraduateStudent(gradl J "203230 1T > ,fl Janet Brown", 
"Parser Generators 11 , "M.$."); 
_setUpGnaduateStudent(grad2,"240900","Hark Black", 
"Code Optimization", "Ph.D,"}; 

_printStudentInfo(studentl); 

_p rintStude ntlnfo(student2}; 

_printStudentInfo(gradl); 

^printStudentlnfofgradS); 

> 

Output: 


Id 

: 120455 

Name 

: Joe Doe 

Type 

; student 

Id 

: 103606 

Name 

: Mary Smith 

Type 

: student 

Id 

: 203230 

Name 

: Janet Brown 

Type 

: Graduate 

Thesis 

: Parser Generators 

Degree 

: H.S. 

Id 

: 240900 

Name 

: Mark Black 

Type 

: Graduate 

Thesis 

: Code Optimization 

Degree 

: Ph.D. 


Figure 6: Client program for Student and GraduateStudent 
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♦include "graduate.h" 

SOHAny *createQbject(SDMAny ^object) 

{ 

return(_somNew(_somGetClass(object))); 

) 

mainC) 

{ 

Student *studentl = StudentNevO; 

GraduateStudent *gradl = GraduateStudentNevO; 
Student *student2; 

GraduateStudent *grad2; 

student? = createObject{studentl); 
grad? = createObject(gradl); 

_setllpStudentCstudent!/T20455 11 , "Joe Ooe"}; 
_setUpStudent(student?/T03606"/'Hary Smith"}; 
.setUpGraduateStudentfgradl,"203230"/'Janet Broun", 
"Parser Generators", "H.S,"); 
_5etUpGraduateStudent(grad2/ l 2409QQ","Hark Black", 
"Code Optimization", "Ph.D."); 

sprintStudentlnfo(studentl); 

_printStudentInfo(student?); 

_printStudentInfo(gradl); 

_printStudentInfo(grad2); 

} 


Figure 8: Client program using class object 



Any number of 
classes can be 
associated with a 
new metaclass. 


• Override the client invoked SOHQass method 
somlewO, which instantiates a new Student 
object. 

• Override the somlnitO method invoked on a 
newly instantiated class object to initialize 
the count to zero. The class definition and 
implementation files for StudentFactory are 
shown in Figure 9, 

• Modify the student class definition files as 
shown in Figure 10. No changes are needed 
to the class implementation file for Student. 

You can now use the new StudentFactory object 
to find out how many student objects have 
been instantiated: 

♦include "student.h" 

mainQ 

{ 

Student *studentl = StudentNevO; 


Student *student2 = StudentNevO; 

SOMQass *studentClassObject; 

_s etUpStudent (studentl, 11 120455"/'Joe Doe 11 ); 
_$etUpStudent(student2,"103606"/'Mary Smith"); 

studentQassQbject = „somGetClass{ studentl); 
printf("Student count: */*d \n", 
_countQbjects(studentCLassObject)); 
print!("studentl class object is of <Ks> dassVi", 
samGetClassName(studentClassObject)); 

} 

with the output: 

Student count: 2 studentl class object is of 
<StudentFactory> class 

IMPLIED METACLASS 

Any number of classes can be associated with 
a new metaclass. For example, instead of 
StudentFactory, we might have used the more 
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Class Definition File: 
include <sorncls.esc> 

class: 

StudentFactory; 
parent: 

SOHQass; 

data: 

int count; 
methods: 

override somlnit; 
override somNeu; 
int countObjectsO; 

Class Implementation File: 

tdefine StudentFactory_Class_$ource 

tinclude "countmet.ih" 

void somInit(StudentFactory *somSelf) 

{ 

StudentFactoryData *somThIs = StudentFactoryGetData(somSelf); 
parent_somInit(somSelf); 

.count s 0; 

> 

SOWAny * somNeu(StudentFactory *somSelf) 

{ 

StudentFactoryData *somThis = StudentFactoryGetData(somSelf}; 
.count ++; 

return (parent_somNeu(somSelf)); 

} 

int countObjects(StudentFactory *somSelf) 

{ 

StudentFactoryData *somThis - StudentFactoryCetData(somSelf); 
return (int) .count; 

} 


Figure 9: Class definition ami implementation files for StudentFactory 


general metaclass name CountFactory to track 
total instantiated objects for many classes, and 
then used this metaclass whenever we want to 
keep track of total instantiated objects. 

Often, we do not want generality, intending a 
particular class object to be associated with 
only one class. For example, if the only change 
to the metaclass is the addition of new 
constructor methods applicable to a specific 
class, we can use a short cut called an implied 
metaclass to redefine the metaclass. The main 
advantage of implied metaclass is that the 


class definition file for the metaclass can be 
folded into the class definition file for the class 
it controls, and similarly for the class 
implementation. 

The student definition and implementation 
files are shown in Figures 11 and 12, 
respectively. Two keywords in the class 
definition define implied metaclass: 
"classprefix" indicates a prefix used to identify 
methods associated with the class object. 
''Class" identifies data members or methods 
associated with the class object. 
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include <somobj.se> 
include "countmet.se" 

class: 

Student; 

metadass; 

StudentFactory, local; 

parent: 

SOMObject; 

data: 

char id[16]; /* student id */ 

char name[32]; /* student name */ 

methods: 

override somlnit; 

void setUp$tudent(char *id, char *name); 
void printStudentlnfoO; 
char *getStudentType(); 
char *getStudentId{); 


Figure 10: Newly modified Student class definition files (modified lines are shown in boldface) 



include <somobj.sc> 
class: 

Student, dassprefix = StudentQass^; 

parent: 

SOMObject; 

data: 

char id[16]; /* student id */ 

char natne[32]; /* student name */ 

int count, class; 
methods: 

override somlnit; 

void setUpStudent(char *id, char *name}; 
void printStudentlnfoO; 
char *get5tudentJype(); 
char *getStudentXd(); 

override somlnit, dass; 

override somNeu, class; 

int eountObjeetsQ, class; 


Figure 31: Student class definition using implied metadass (changes from original Student shown in boldface) 
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fldefine Student.Class.Source 
tinclude "student.lh" 

SOM.Scope void SOHLINK somlnitfStudent *$om$elf) 

{ 

StudentData *soinThis = StudentGetData(somSelf); 
parent_son]Init{somSelf); 

_id[0] = .name [03 = 'VO'; 

} 

/* Other Student Methods, as before, followed by,,, */ 
#undef SOM.CurrentClass 
#define $DM_CurrentClass SOMMeta 

SOM.Scope void SOMLINK StudentClass.somlnitC 
M.Student *somSe!f) 

{ 

M.StudentData tsomThis = M.StudentGetData(somSelf); 
parent.somlnit($om$elf); 

.count = 0; 

} 

SOM.Scope SOM Any *$QMLINK StudentQass_soniNew( 

M.Student *som$elf) 

{ 

M_StudentData *somThis = M_StudentGetData(somSelf); 

.count ++;\ 

return {parent_somNew(somSelf)}; 

} 

SOM.Scope int SOMLINK 5tudentClass.countGbjects( 
M.Student *som$elf) 

{ 

M.StudentData *$omThis » M.StudentGetData(somSelf); 

return (int) .count; 

> 


Figure 12: Student class implementation using implied metaclass (programmer added tines shown in boldface) 


The output, which had looked like: 

Student count: 2 

studentl class object is of <StudentFactory> class 
now looks like: 

Student count: 2 

studentl class object is of <M_Student> class 

The difference in output reflects the system 
assigned name of the metadass. 


SUMMARY 

The class object is an important source of run¬ 
time information in SOM. The class object is a 
fully functional object like any other object in 
SOM. It has its own class (default SOMCLass) that 
can be modified with any of the normal class 
modification techniques, including inheritance 
and polymorphism. 

The class object is an important programmer 
resource. The source of run-time class 
information, it gives you the ability to make 
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run-time decisions about how objects are 
manipulated. Because it is a standard SOM 
object, instantiated from a standard SOM class, 
there is considerable flexibility to redefine its 
characteristics as needed. 
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32-Bit OS/2 



The OS/2 Workplace 
Programming Interface 


by Mary A . Wright 

In OS/2 jLy, the Desktop is a collection of windo ws 
or icons representing windows associated with 
applications. In OS/2 2,0, the Desktop is a 
collection of objects (or icons) and windows 
associated with those objects. The Desktop (which is 
also an object), the objects that appear on the 
Desktop, and the underlying code supporting these 
objects constitute the OS/2 Workplace Shell , the 
default user interface for OS/2 2.0 , 
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Figure 2: Workplace Shell desktop 


While object-oriented user interfaces share some 
concepts with object-oriented programming , user 
objects may not necessarily correspond to software 
objects. Object-oriented programming can make the 
development of an object-oriented user interface 


easier. However f an object-oriented user interface 
can be developed with more traditional 
programming languages and toots. 

The OS/2 2.0 Workplace Shell is an example of a 
user interface developed using object-oriented 
programming , specifically the IBM System Object 
Model (SOM). Application developers can easily 
design applications for the new paradigm. 
Workplace applications consist of sets of related 
objects used to perform a set of tasks. In addition to 
providing a consistent and easy-to-use user 
interface, Workplace applications offer all the 
advantages provided by object-oriented 
programming techniques, such as modularity , 
reusability, and so on. 

This article is an introduction to the Workplace 
programming interface , which consists of the 
predefined Workplace classes and functions 
provided with the OS/2 2.0 Toolkit , Application 
developers can take advantage of the function 
provided by the Workplace by deriving their new 
classes from, or subclassing f the predefined 
Workplace classes. 


THE WORKPLACE SHELL 

P rior to 1991, Common User Access (CUA) 
guidelines defined the user interface for 
application-oriented environments. In 
application-oriented environments such as 
OS/2 Lx, users perform tasks by starting an 
application. They start an application by 
selecting an installed program from a list 
displayed in a window or by entering the 
program name at a command-line prompt For 
example, users can start an editor to create and 
edit a file, start a spreadsheet application to 
create and update a spreadsheet, or send a file 
to a printer. 
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In 1991, CUA guidelines defined the user 
interface for object-oriented environments, fn 
object-oriented environments such as OS/2 
2.0, users perform tasks by manipulating on¬ 
screen objects. Users do not start an 
application to perform a task. Instead, they 
select an action or drag the object and drop it 
on another object to perform a task. For 
example, users can select the OPEN action on a 
file object to start an editor to work on the file 
and drag the file object and drop it on a printer 
object to print it. 

The concept of applications is transparent to 
the user. Users interact with objects rather than 
with the operating system or separate 
applications. They focus on the task and not on 
the tools used to perform the task. Users 
interact with objects in the same manner across 
tasks. 

New Features for OS/2 2.0 

The OS/2 Workplace Shell provides an object- 
oriented user environment based on the 1991 
CUA guidelines. In the OS/2 2.0 Workplace 
Shell, applications from OS/2 1.x are replaced 
by objects and collections of objects or folders. 
Objects correspond to devices {such as 
printers), applications (.EXEs), and file objects 
(such as files, subdirectories, and drives). 
Objects can be organized by users into folders, 
which are also objects. 

Object names or labels can be equivalent to the 
objects they represent. For example, the object 
that represents the program file MYAPP.EXE 
can be named MYAPP.EXE. Object names can 
also be changed to whatever is meaningful. 

For example, the object that represents the 
program file MYAPP.EXE can be relabelled 
"My Application." Where an object resides is 
also transparent to users. For example, an 
object can represent a printer device that is 
physically attached to the user s system or 
attached through a network. Figure 1 shows 
the desktop in the new object-oriented user 
environment. 

Some of the objects the Workplace Shell 
provides are described in Table 1. After 
installation of OS/2 2.0, some of them appear 
directly on the Desktop. Some of them are 
contained in folders. Users can rearrange and 
relabel them to suit themselves. 


WORKPLACE CLASSES 

Every user object in the Workplace Shell is an 
instance of a Workplace software class object. 
There is a one-to-one correspondence between 
Workplace (user) objects and Workplace 
(software) classes. This is evident in the class 
hierarchy for Workplace objects, shown in 
Figure 2. 

Workplace classes are defined using SOM's 
Object Interface Definition Language (OIDL). 
Workplace class libraries are built using the 
SOM compiler. Workplace objects are 
instantiated by the Workplace on behalf of the 
user through the Workplace Class List Object, 
installation programs, or batch files. The same 
rules that apply to SOM classes apply to 
Workplace classes, with the exception that 
applications cannot call Workplace methods. 
(SOM client applications can call SOM 
methods.) 
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Figure 2: Hierarchy vf Workplace objects 


Characteristics and behavior for objects 
belonging to a class are defined as new 
methods for the object's class as well as 
methods inherited from ancestor classes. 
Workplace objects can take advantage of 
characteristics and behavior provided by 
existing Workplace classes by subclassing 
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SOME WORKPLACE OBJECTS PROVIDED BY OS/2 2,0 


Object 

Purpose 

Clock 

Set and view the current date, time, and alarm 

Country 

Set and view international conventions for system 
elements (country, date,time, and numbers) 

Keyboard 

Set and view keyboard configuration (timing, 
mappings, and special needs) 

Mouse 

Set and view behavior of mouse device (timing, 
setup, and button mappings) 

Scheme Palette 

Set and view window color and font attributes 

Font Palette 

Set and view fonts for textual elements of user 
interface and apply fonts to windows 

Color Palette 

Set and view colors for visual elements of user 
interface and apply color to a window 

Printer 

Set and view a print destination (a print queue and 
its associated port) 

Shredder 

Destroy an object 

Sound 

Enable or disable warning beep 

Special Needs 

Explain implications of special needs mode when activated 

Spooler 

Enable or disable spooling; set and view spool path 

System 

Set and view behavior of system elements 
(confirmations, logo, and windows) 


Table I: Workplace objects provided by OS/2 2,0 


WORKPLACE STORAGE CLASSES 


Class 

Storage of Object Instance Data 

WPAbstract 

Object instance data stored in user profile (OS2.INI) 

WPFileSystem 

Object instance data stored in files in the file system 

WPTransient 

Object instance data not saved 


Table 2: Workplace storage classes 
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those classes or deriving their new class from 
the existing classes. 

All Workplace classes are derived from a root 
Workplace class, WPObject, which is derived 
from the root SOM class, SOMQbject. WPObject 
defines behavior common to all Workplace 
objects. The immediate descendants of WPObject 
are storage classes from which all other 
Workplace classes are derived. Storage classes 
define methods for storing and retrieving data 
associated with instances of descendant 
classes. Storage classes provided with the 
Workplace Shell are shown in Table 2, 

Objects whose instance data and state are 
preserved between system shutdown and 
system startup are called persistent objects. 
Objects whose instance data and state need not 
be preserved between system shutdown and 
system startup are called nonpersistent objects. 


DESIGNING WORKPLACE 
CLASSES 

To design a Workplace class, first identify all 
the actions to which an object instance can 
respond. Based on this list, define the methods 
in the class definition file that correspond to 
the actions identified. To illustrate this process 
and understand how method requirements for 
a class are identified, consider the following 
general description of objects and how it is 
used to define the WPObject class. 

Based on the general description of user 
objects in a CUA-conforming user 
environment objects have: 

* Properties {for example, an icon 
representation on the Desktop) 

* Views that contain information about the 
object 

* Context or pop-up menus that describe 
actions to which the object can respond 

* Mobility (objects can be directly 
manipulated). 


definition file for the WPObject class. Table3 
shows the mapping of characteristics and 
behaviors common to all Workplace objects to 
method groups defined for the WPObject class. 


SETTINGS NOTEBOOK METHODS 

The WPObject class provides for a standard page 
in a Workplace object's settings notebook 
called a General page. This page describes all 
the general object properties (title, icon, and a 
user-definable setting to specify whether or 
not this object is a template). All Workplace 
objects have general properties associated with 
them; therefore, all Workplace objects have a 
General page in their settings notebook. 



DEFINING METHODS FOR THE WP OBJECT CLASS 

Method Group 

Characteristic or Behavior 

Settings Notebook 

Describe properties of an object 

Save and Restore State 

Persistence of Object Instance Data 

Object Usage 

Object Usage Information 

Pop-up Menu 

Actions that users can perform on 
objects 

Set and Query 

Object information (views, style, 
and title) 

Error Handling 

Error returns from object methods 

Memory Management 

Memory allocation for object 
resources 

Setup and Cleanup 

Object initialization and 
termination 

Direct Manipulation 

Object mobility (drag and drop) 


Table 3: Defining methods for the Workplace object class 


Because WPObject defines general characteristics 
and behaviors common to all Workplace 
objects, these characteristics and behaviors 
should be reflected in the methods in the class 


Settings notebook pages for Workplace objects 
are inherited from ancestors of their 
Workplace class. They include pages that have 
been added or removed by ancestor classes, in 
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YourObject Settings 


This page is not 
inherited from 
YourObject’s 
ancestors. 

General 


MyPage_1 


MyPage_2 



YourPage 




MyObject Settings 


This page is not 
inherited from 

MyObject’s ancestors. 

General 


MyPage_1 



MyPage_2 



Figure 3; Settings notebook pages for My Object and tour Object 
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SETTINGS NOTEBOOK METHODS 

Method 

Description 

wpAddDbjectGeneralPage 

Add the General page to the object's 
settings notebook 

vpAddSettingsPages 

Add pages to the object's settings 
notebook 

wpInsertSettingsPage 

Insert a page into the object's 
settings notebook 


Table 4: Settings notebook methods 


addition to the General page inherited from the 
root WPQbject class. For example, suppose that 
My Object is a class of persistent objects derived 
from the UPAbstract class. Because UP Abstract is 
derived from UPObject, MyObject inherits 
characteristics and behaviors from UP Abstract 
and UPObject. UP Abstract inherits its settings 
notebook from UPObject. My Object, therefore, 
also inherits WPObject's settings notebook, 
which consists of a general page. 

Suppose My Object defines two additional pages 
in its settings notebook: My Page, 1 and MyPage_2. 
This means that the settings notebooks for 
MyObject have three pages: General, MyPage_l, and 
MyPage_2 + Now suppose YourObject is derived 


from MyObject and, therefore, by inheritance, 
instances of Your Object have a General page as 
well as MyPage_l and MyPage_2 in their settings 
notebooks. Also suppose YourObject defines an 
additional page in its settings notebook: 
YourPage. The settings notebook for YourObject 
has four pages: General (inherited from the 
UPObject class), MyPage.l, MyPage_2 (inherited 
from MyObject), and YourPage. The pages in the 
settings notebooks for MyObject and YourObject 
are shown in Figure 3. 

The settings-notebook methods, as shown in 
Table 4, allow you to add new pages or 
remove pages a class has inherited from its 
ancestor's settings notebook. 
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When a user requests the object's settings 
view, the shell builds the object's settings 
notebook by calling the object's 
wpAddSettingsPage method. If the object shares 
the settings notebook of its parent class, the 
wpAddSettingsPages method belonging to the 
object's parent class is called. 

New pages are added to the settings notebook 
an object inherits from its ancestors by 
overriding the object's wpAddSettingsPage 
method and: 

* Calling a new method that inserts the new 
page. 

* Calling the wpAddSettingsPage method 
belonging to the object s parent class 
(parent_wpAdd$ettingsPage). 

The new method calls the wpInsertSettingsPage 
method to insert the new page into the object's 
notebook. This technique is shown in Figure 4. 

New pages for an object s settings notebook 
can be placed at the top or bottom of pages 
inherited from the object's ancestors. By calling 
the parent.wpAddSettingsPage method before 
calling the new method (vpAddAnotherPage), the 
new page is added to the top of the settings 
notebook, before pages inherited from the 
object's ancestors. If the sequence is reversed, 
the new page is added to the bottom of the 
settings notebook, after the pages inherited 
from the object's ancestors, 

A page can be removed from an object's 
settings notebook by overriding the ancestor's 
method that inserts it. From the previous 
example, the settings notebook for Your Object 
inherits the pages (General, MyPage.l, and 
MyPage_2) defined by its ancestors (ttyObject and 
WPGbject), But YourObject may have 
requirements for MyPage.i but not MyPage_2, To 
remove MyPage_2 from YourQbject's settings 
notebook, YourObject must override the method 
inherited from My Object that adds ttyPage_2 to 
the settings notebook and return 
SETTINGS_PAGE_REMOVED without calling the parent 
method. This method is illustrated in Figure 5. 

The same technique can be used to replace or 
remove the General page from an object's 
settings notebook by overriding the 
wpAddSettingsPages and ypAddObjectGeneralPage 
methods. The override to wpAddSettingsPages 


calls the ypAddObjectGeneralPage method. To 
remove the General page, the override to 
wpAddObjectGeneralPage returns 
SETTINGS_PAGE_REMOVED without calling the parent 
method. To replace the General page with 
another page, the override to 
wpAddObjectGeneralPage calls wpInsertSettingsPage 
without calling the parent method. 



/********************* New Methods ***************************/ 

SQM_5cope UL0NG SOMLINK MyQbject w ypAddAnotherPage(My0bjeet *somSelf, 
HWND hundNotebook) 

{ 

PAGEINFD pageinfo; 

I* Set up page information data structure for my new page, */ 

/* Add the page to the Settings Notebook */ 

return _upInsertSettingsPage(som$elf, hundNotebook, ftpageinfo); 

} 


/*******************++ Method Overrides ***************************/ 

SOM,Scope B00L32 SOMLINK MyObject.wpAddSettingsPage (ttyObject 
♦somSelf, 

HWND hundNotebook) 

{ 

if (parent^wpAddSettingsPage (somSelf, hundNotebook) 

M _wpAddAnotherPage (somSelf, hundNotebook)) 

return (TRUE); /*pages added successfully */ 

else 

return (FALSE); /^something failed -return error */ 

> 


Figure 4: Adding pages to an object's settings notebook 


f********************* Method Overrides ***************************/ 
SOM.Scope ULDNG SOMLINK YourQbject_wpAddAriotherPage(YourObject 
♦somSelf, 

HWND hundNotebook) 


{ 


/* Remove this page from the Settings notebook. */ 

return (SETTINGS^AGE REMOVED); 

> 


Figure 5: Removing a page front an object $ settings notebook 
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POP-UP MENUS 

Pop-up menu methods support the actions 
users can perform on an object. These actions 
appear in a context or pop-up menu when the 
user presses button 2 of the pointing device. A 
pop-up menu, as shown in Figure 6, contains 
action choices for an object in its current 


Open (->) 

x Settings 

Help 

Details 

Print {->) 



Figure 6: Pop-up menu options 


context, or state. The contents of a pop-up 
menu depends on the state of the object. 

Pop-up menus consist of a set of selectable 
items and any pull-down or conditional 
cascade menus associated with them. In Figure 
6, Open, Help, and Print are items in the object's 
primary pop-up menu. Settings and Details are 
items in the Open pull-down or conditional 
cascade menu. Conditional cascade menus 
have mini buttons displayed next to the pop¬ 
up menu item. If users select the pop-up menu 
item, a default action listed in the pull-down 
menu is performed. If users select the mini 
button, the pull-down menu is displayed. It is 
a conditional cascade menu because it is 
displayed only if the user selects the mini 
button. 


POP-UP MENU METHODS TO MODIFY AN 

OBJECT'S POP-UP MENU 

Method 

Description 

vpFilferPopupMenu 

Filter out options from object's pop-up 
menu that don't apply 

wpInsertPopupMenuItems 

Insert items into object's pop-up menu item 

wpModifyPopupMenu 

Add new options to the object's pop-up 

menu 


Table 5: Pop-up menu method* to modify an object's pop-up menu 


/* Method Override */ 

/* Filter out any options from the pop-up that don't apply. */ 

SQM_Scope ULQNG SOHLINK MyObject_wpFilterPopupHenu(MyObject *somSelf, 
ULDNG ulFlags, HWND hvndCnr, G00L32 fHultiSelect) 

{ 

MyObjectData *somThis = MyObjectGetData(somSelf); 

MyObjectMethodOebug( n HyObject","MyObject_upFilterPopupMenu"); 

/* Don't allow anyone to print MyObject */ 

return( parent.wpFilterPopupMenu(somSelf,ulFlags,hwndCnr,fMultiSelect) 

& TTXT.PRINT ); 


} 


Figure 7: Removing standard items from an object's pop-up menu 
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Like settings-notebook pages, pop-up menus 
are inherited from a class's ancestor classes. 
They include pop-up menu items ancestor 
classes have added to or removed from the 
pop-up menu inherited from WPObject. Hie 
pop-up menu methods shown in Table 5 allow 
users to add or remove new menu items from 
the pop-up menu inherited from an object's 
ancestor classes. 

When users request an object's pop-up menu, 
the Shell builds the object's pop-up menu by 
calling the object's wpFilterPopupMenu and 
wpModifyPopupMenu methods. The 
wpInsertPopupMenuItems method is called by an 
override to the upModif yPopupMenu method to add 
new options to an object's pop-up menu. 

Adding and Removing Items from a 
Pop-Up Menu 

The WPObject class defines a set of standard 
pop-up menu items that are inherited by all 
Workplace objects. The pop-up menu of a 
Workplace object consists of a subset of the 
standard pop-up menu items and any new 
menu items defined for the object's class or 
inherited from other ancestors. 

Workplace classes can add or delete standard 
pop-up menu items from their pop-up menu 
by overriding the vpFilterPopupMenu method. 
Each standard pop-up menu item is associated 
with a flag defined by the WPObject class. The 
flags are represented by constant names 
prefixed by CTXT_ and are defined in the toolkit 
header files. 
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The wpFilterPopupMenu method returns the flags 
that represent the pop-up menu items for the 
object. In removing a standard pop-up menu 
item from the pop-up menu, the override to 
wpFilterPopupMenu masks the flag that 
corresponds to the item being removed from 
the flags that represent the standard pop-up 
menu items inherited from the object's parent. 
For example, suppose that printing My Object 
has no meaning. To remove the Print option 
from MyObject's pop-up menu, wpFilterPopupMenu 
is overridden as shown in Figure 7. 

In this example, flags that represent the 
standard pop-up menu items of My Object's 
parent class are returned from the call to 
parent^wpFilterPopupMenij. To remove the Print 
option from MyObject's pop-up menu, these 
flags are ANDed with the complement of 
CTJCLPRINT. Conversely, if the pop-up menu of 
MyObject's parent class did not include the Print 
option, it can be added to My Object's pop-up 
menu by ORing these flags with CTXT_PRIMT. 

An object's pop-up menu is inherited from its 
ancestors. To ensure that calls to the 
wpFilterPopupMenu method belonging to the 
object's ancestors do not add the menu item 
after it is deleted or remove the menu item 
after it is added, the parent,ypFilterPopupMeru 
method is called first- 

Adding Class-Specific Items to the 
Primary Pop-Up Menu 

New items are added to the pop-up menu 
inherited from an object's ancestors by; 

* Defining a new method that returns flags 
representing the new items being added to 
the object's pop-up menu. 

* Overriding its wpModifyPopupMenu method and 
calling the wpInsertPopupMenuIteFns method if 
the flag associated with the menu item is set. 

For example, to add "New Item" to HyObject's 
pop-up menu, the new menu item is defined 
in a resource file in the same manner as menus 
are defined in PM programs. An ID is assigned 
to the new menu and to the menu item, as 
shown in Figure 8. 


items defined by the Workplace classes 
provided with the Shell, 

A new method for My Object, wpMy Filter PopupMenu, 
returns a flag that represents the new item 
added to the inherited pop-up menu for 
My Object. The override to wpModifyPopupMenu uses 



#define ID.MOREITEMS 

WPMENUID.USER+l 

Sdefine IDJEWITEMS 

WPMENUID.USER+2 

MENU ID.MOREITEMS LOSDONCULL MOVEABLE DISCARDABLE 

BEGIN 


MENUXTEM "New Item", 

IDJEWITEMS 

END 



Figure 8; Resource file defining new items for object's pop-up menu 


/* Define MYCTXTJEWITEH here */ 


/* New Method */ 

l* Filter new items added to MyObject's pop-up menu */ 

S0M_Scope ULQNG SQMLINK MyObject_wpMyFilterPopupMenu(MyQbject*somSelf, 
ULOKG ulFlags, HWND hyndCnr, B00L32 fMultiSelect) 

{ 

return (MYCTXTJEWITEM); 

> 

/* Method Override */ 

/* Add a new item to MyObject's pop-up menu */ 

SGM_$cope BQQL32 SQMLXKK MyObject.wpModifyPopupMenu(MyObject 
♦somSelf, 

HWND hvmdMenu, HWND hyndCnr, ULDNG ulPosition) 

{ 

/* Get flags for new items for MyObject's pop-up menu */ 

flags=_vpMyFilterPopupMenuf...); 

/* Insert ney items in MyObject's Primary Menu if flag is set */ 
if (flags & MYCTXTJEWITEM) 

_ypInsertPopupMenuItemsA(somSelf, hwndMenu, ulPosition, hmod, 
IDJDREITEMS, WPMEWt>ID .PRIMARY); 

/* Add the items inherited from MyObject's parent */ 
return (parent_ypModifyPopupMenu(somSelf,hwndMenujhwndCnr,ulPosition)); 
} 


IDs for class-specific menus and menu items 
have a value greater than WPMENLUDJSER, so they 
do not conflict with IDs for menus and menu 


Figure 9: Adding class-specific items to an object's pop up menu 
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/* Insert new items in MyObject's Open SubMenu if flag is set */ 
if (flags ft NYCTXTJEHITEM) 

.upInsertPopupMenuItemsJKsomSelf, hwndrtenu, ulPosition, hmod, 
IDJOREHEMS, WPMENUIDJJPEN); 


Figure 10: Adding an item to a pop-up menu submenu 


/* 

Method Override 

*/ 

/* Filter i 

new items added to MyObject's pop-op menu 

*/ 

SQH.Scope ULONG SOHLINK YourQbject_wpMyFilterPopupMenu( 


YourObject 

{ 

*somSelf, ULONG ulFlags, HWND hwndCnr, B00L32 fttultiSelect) 

return{0); 

/* Return no flags so that 'New Item' is not 

*/ 

> 

/* included in YourObject'$ pop-up menu 

*/ 


Figure II: Removing class-specific items from a pop-up menu 


POP-UP MENU METHODS THAT SUPPORT 

NEW POP-UP MENU ITEMS 

Method 

Description 

ypMenuItemHelpSelected 

Display the help associated with class-specific pop-up 
menu item 

ypMenuItemSelected 

Process class-specific pop-up menu items 


Table 6: Pop-up menu methods that support neu> pop-up menu items 


the flags returned from ypMyFilterPopupMenu to 
determine which items are inserted in 
MyObject's pop-up menu. This technique is 
illustrated in Figure 9, 

The wpInsertPopupMenuItems method requires a 
handle to the module where the menu 
resource is defined, the ID for the menu 
resource, and the ID for the menu where the 
item is being inserted. In this example, 
IDJOREITEMS is the ID for the menu resource 
that defines the new menu item being added 
to the object's primary pop-up menu. 


MPHENUID.PRIHARY is the ID for the object's 
primary pop-up menu, where “New Items" is 
being inserted. 

An item can be added to a pop-up menu's 
submenu or conditional cascaded menu by 
specifying the ID for the conditional cascaded 
menu on the call to wpInsertPopupMenuItems. For 
example, to add “New Items" to the Open 
conditional cascaded menu, the call to 
ypInsertPopupMenuItems is modified as shown in 
Figure 10. 
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WORKPLACE API 


Function 

Description 

WinCreateObject 

Create an object 

WinDeregisterDbjectClass 

Deregister (remove) a Workplace object class 

WinDestroyQbject 

Delete a Workplace object 

WinEn uoiOb j ectCla sses 

Get a list of all Workplace classes that have been 
registered 

WinQueryObject 

Get a handle to a given object 

WinRegisterObjectClass 

Register a Workplace object class 

WinReplaceObjeetClass 

Replace a registered class with another registered class 

WinSetObjectOata 

Change settings on an object that was created with 
tfinCreateQbject 


Table 7: Workplace API 


REXX UTILITY WORKPLACE FUNCTIONS 

Function 

Description 

SysRegisterQbjectClass 

Register a Workplace object class 

Sy sDeregiste rQbj ectCla s s 

Deregister a Workplace object class 

SysQueryClassList 

Get the list of Workplace class registered with the Shell 

SysCreateObject 

Create a Workplace object 


Table 8: REKX utility workplace functions 


Removing Class-Specific Items from a 
Pop-Up Menu 

Class-specific pop-up menu items inherited 
from ancestor classes are removed by 
overriding the methods that return flags 
representing those items. For example, 
suppose My Object is the parent class of 
YourQbject, but YourObject has no requirement 


for the '"New Item'' in the pop-up menu it 
inherits from HyObject. 

To remove "New Item" from YourGbject's pop¬ 
up menu, YourGbject's class overrides 
wpHy FilterPopupMenu and does not return the 
MYCTXTJEWITEM flag that My Object defined for 
"New Item." This technique, shown in Figure 
11, is similar to that described for removing 
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standard items from an object's pop-up menu, 
It requires that My Object publish 
wpHy FilterPopupMenu as well as the MYCTXT JEUTEM 
flag so that subclasses of My Object can remove 
or add "New Item/' 

Supporting User Selection o f New 
Pop-Up Menu Items 

When a class defines new actions for its pop¬ 
up menu, it must provide for the processing of 
the actions when the user selects them. This is 
done by overriding the pop-up menu methods 
shown in Table 6, 


SUPPORTING USER SELECTION OF NEW 
POP-UP MENU ITEMS 


/* Method Override */ 

/* Process input from the extra menu option that we added. */ 


SOM^Scope void 

{ 


SQMLINK MyQbject.vpMenuIternSelected(MyObject *self, 
mm hwndFrame, ULGNG MenuID) 


/* Which of our menu items was selected ? */ 
switch( MenuXd ) 

{ 

case ID.SUBITEMl: 


case IMUBITEM2: 
case ID_SU8ITEM3: 


case ID,SUBITEM4: 


} 


default: 

parent.wpMenuItemSelected 


Figure 12: Supporting user selection of new pop-up menu items 


Using the previous example, MyObject supports 
SubXtem_l by overriding the wpMenuItemSelected 
method as shown in Figure 12. 


THE WORKPLACE APPLICATION 
INTERFACE 

Outside the Workplace environment, objects 
are dynamic link libraries that consist of data 
and code operating on that data when objects 
are instantiated in the Workplace (run-time) 
environment. Workplace objects have no life 
outside the Workplace environment. 

Workplace classes come to life when the class 
is registered with the Workplace Shell and the 
class is instantiated. The Workplace Shell and 
SOM provide the underlying code {predefined 
Workplace object methods) that supports an 
object's existence. The Shell calls the 
appropriate object methods when the user 
interacts with the object In this sense, the Shell 
is the client of all Workplace objects. The Shell 
manipulates the object (its code) on behalf of 
its users. 

Applications, on the other hand, cannot call 
Workplace object methods directly. They are 
not clients of Workplace objects in the same 
sense that applications can be clients of SOM 
objects. Workplace objects are derived from 
the WPObject class, which is derived from the 
SOMObject class. They share all the features of 
SOM objects: inheritance, polymorphism, and 
so on. But only the Shell can directly 
manipulate them. 

Because there are times when applications 
may need to make changes to the Desktop and 
objects on the Desktop, the Workplace Shell 
provides functions that enable your 
application to effect those changes. These 
functions are summarized in Table 7. 


REXX UTILITY WORKPLACE 
FUNCTIONS 

The REXX programming language also 
provides utility functions for Workplace 
classes and objects. These functions are listed 
in Table 8. 


MyObject support helps for new pop-up menu 
items by overriding vpMenuItemHelpSelected in a 
similar manner. 


REXX utility functions allow users to write 
batch files to operate on Workplace classes and 
objects in the same way as applications. 
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Installing a Workplace Object 

Workplace objects can be installed on the 
Desktop in one of two ways: 

* By running an installation program or batch 
file 

* By using the Workplace class list object. 

Application developers can provide 
installation programs for their objects. From 
the user's perspective, installation consists of 
putting a diskette in the diskette drive, double¬ 
clicking on the diskette drive, and then on the 
installation program. 

An installation program is responsible for: 

* Copying the dynamic link library (DLL) that 
contains the object's class definition from a 
disk to the \OS2\DLL directory or to a 
directory in \LIBPATH 

* Registering the class and its DLL name with 
the Shell by calling WinRegisterObjeetClass 

* Creating an object instance of the class and 
placing it on the Desktop or in a particular 
folder by calling WinCreateQbject 

Instantiating an object is an optional 
responsibility for an installation program. 
When a class is registered by caliing 
UinRegisterObjectClass, an object template is 
placed in the Templates folder on the Desktop 
if the class supports templating. Users can 
create instances of these objects by tearing off a 
copy of the template. This strategy can be 
useful for larger applications that define data¬ 
file objects associated with program objects. 

An installation batch file written in REXX 
performs the same operations, but uses the 
REXX utility functions SysRegisterObjectQass, 
SysCreateGbject, and SysDeRegisterObjectClass 
instead of the WinRegisterObjectQass, 
VinCreateQbject, and WinDeRegisterObjectClass 
Workplace functions. 

The OS/2 2*0 toolkit provides a Workplace 
class list object that is automatically installed 
during installation of the toolkit This object is 
a tool that provides a windowed user interface 
for general Workplace class registration and 
object creation activities* It performs all the 
functions a typical Workplace object 


installation program must provide, with the 
exception of copying files from an installation 
diskette to a hard disk. It is a fast and easy way 
to build and test objects in an application- 
development environment. It is not a tool for 
the general OS/2 user who knows nothing 
about Workplace classes. 

Mary Wright, /BM Personal Systems LOB, 1000 
N.W. 51st SL, Boca Raton, Fla., 33429 ' Mrs. 
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Multimedia and Graphics 

DVI Support by 
Audio Visual Connection 



Kai-ching Chit 


by Kahcfiing Chit 

The ActionMedia II™ display hoard, based on the 
technology of Digital Video Interactive (DVI), can 
play back video and image files on the IBM PS/2 
"on the fly ." With the addition of the recently 
released Audio Visual Connection ™ 1,05software, 
users can combine digitally generated video and 
still images with VGA and XGA images, text t and 
APCA sound to create a complete presentation. 

This article discusses the design of A VC-DVI 
support and of A VA, an extended authoring 
language that handles DVI file playback. It includes 
examples of how to control playback 
synchronization and achieve various dynamic audio 
and visual effects . 


Programmers 
can develop 
poiverful and 
cost-effective 
digital video 
applications that 
convert the PS/2 
into a 
multimedia 
desktop 
computer. 


DVI, ACTIONMEDIA, AND AVC 

I BM and Intel's recent advances in DVI 
technology enable users to capture, digitize, 
and compress audio and video signals. Once 
compressed, full-motion video signals can be 
played back from storage devices such as CD- 
ROM, rewritable optical disks, and magnetic 
hard disks. 

With these advances and the 1992 introduction 
of IBM's PS/2 ActionMedia II adapter (which 
uses DVI processing chips for display, 
compression, and decompression), 
programmers can develop powerful and cost- 
effective digital video applications that convert 
the PS/2 into a multimedia desktop computer. 

Audio Visual Connection™ (AVC) is an 
award-winning PS/2 program that lets users 
author and present multimedia 
demonstrations and applications. Through the 
M - M o fci on V id eo A d a p ter T , co m p u ter 
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graphics images and text can be combined 
with audio and analog video sources in AVC 
presentations. Beginning with AVC 1.05, 
support of DVI sources is provided through 
the ActionMedia 1J adapter board. With 
digitized video, audio or still image files, the 
new AVC program now provides a powerful 
and complete solution for your presentation 
needs. Digital video files are portable, can be 
copied and transmitted, and can be accessed 
from PCs, detachable storage devices, or LAN 
servers. AVC brings vivid and dynamic video 
to advertising, training, education, and other 
applications. 

At the 1991 Comdex/Fall Show in Las Vegas, 
Nev v ActionMedia II hardware and software 
won "Best Multimedia Product" and "Best of 
Show" awards. AVC with DVI support has 
been instrumental in demonstrating DVI 
technology and products, as well as the 
potential for multimedia applications. 


DIGITAL VIDEO AND AUDIO 
IN PRESENTATIONS 

Without compression, a digitized video data 
stream would take up several hundred 
kilobytes to several megabytes per image 
frame, depending on the resolution and color 
depth of the images. For full motion video, 
there are up to 30 image frames per second In 
the data stream to be processed. 

ActionMedia II handles two types of 
compressed video files. Production Level 
Video (FLV) and Real Time Video (RTV). Both 
have an average compression ratio of more 
then 100:T While PLV files can be produced 
off line by Intel's digital compression facility, 
the lower quality RTV files can be captured 
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and compressed in real time by an IBM PS/2 
with ActionMedia II PLV and RIV files can be 
decompressed and played back "on the fly" on 
a PS/2, 

DVI files' audio streams use Pulse Code 
Modulation (PCM, 8-bit samples) or Adaptive 
Differential Pulse Code Modulation (ADPCM, 
4-bit samples) compression algorithms. 

ActionMedia II still images can be stored 
compressed or uncompressed, in 9- and 16-bit 
per pixel formats, ActionMedia 11 also 
supports a 9-bit baseline format of the joint 
Photographers Expert Group (JPEG) Standard, 
which is adopted by the International 
Standards Organization. 

HOW DVI AND AVC 
WORK TOGETHER 

AVC program support for DVI was built with 
the Audio Video Kernel (AVK), an application 
programming interface for ActionMedia II. 
OS/2's multithreaded programming technique 
and dynamic link libraries are used in AVC to 
control different audio and video sources, 
which can be used in synchronous multimedia 
presentations. 


A complicated presentation might combine 
VGA and XGA images with DVI still images 
and DVI video (which require decompression 
on the fly). Audio can come from either the 
Audio Capture and Playback Adapter (ACPA) 
or DVI. All of these sources need to be well 
coordinated and synchronized. 

When DVI images are displayed on a PS/2 
monitor already showing a VGA or XGA 
image, the DVI images appear on a plane 
behind the VGA/XGA image, "showing 
through" any transparent areas of that image. 
These two planes allow overlay of image, text 
or video. Multithreaded programming 
techniques allow efficient switching between 
several computing tasks. While playing the 
video or audio for AVC, for example, a user 
can manipulate overlay text or images on the 
screen or alter certain video and audio control 
parameters. Figure 1 shows how text and 
images can be layered on the screen. 

DVI pictures can be either displayed on the 
PS/2 screen or directed to a TV monitor 
through the S-video output line of the 
ActionMedia II Adapter. In the latter mode, 
AVC story lines and VGA/XGA images are 
shown on the PS/2 monitor while DVI video 
or still images are viewed on a separate TV or 
transmitted to a VCR. 


Multithreaded 
programming 
techniques allow 
efficient 
switching 
between several 
computing tasks. 
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Figure 1: A VC V dual display for DVi video/image overlap 
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AVA: THE AUTHORING 
LANGUAGE OF AVC 

Using A VCs Story Editor, AVC stories are 
written in the Audio Visual Authoring (AVA) 
language, a high-level interpretive language 
for assembling lines of logic describing audio¬ 
visual presentations. The operators and 
instructions of AVA are a subset of REXX, The 
AVC package has a run-time module to run 
the stories. 

Since the AVA language is interpretive, AVC 
story writers can create and modify their 
presentations interactively, AVA has logical 
instructions and structured programming 
capabilities to display and control media and 
direct the flow of stories. Internal or external 
macro subroutines can be used repetitively or 
within controlled phrases. 

Prior to the release of AVC 1.05, the basic AVA 
instructions were PLAY for ACPA audio files 
and SHOW for images {MCGA, VGA, and XGA). 
With the addition of other AVA instructions, 
AVC has the power to construct complex 
stories and link to external environments. It 
can also call external programs, mainframe 
connections, and SQL database services. 


DVI INSTRUCTIONS 
INCLUDED WITH AVA 

With DVI support added to AVC 1.05, the 

AVA language now includes: 

* DPLAY plays a DVI file (video and audio). 

* DSHOW displays a DVI still image. 

* DCQNFIG controls the DVI playing 
configuration, 

* DLQCATE defines source and target image size 
and location. 

* DPAUSE pauses a video sequence, 

* DEJUERY returns the current video frame 
number and play status. 

* DSTATE saves current or restores previous 
state values. 

* D5TEP advances the DVI video one frame. 


* DSTOP stops the DVI video or audio. 

* WAIT D waits for a specific video frame 
number. 

Figure 2 shows a simple use of DPLAY. The 
image is launched until a key is pressed. 



DPLAY M C:\VIDEQ\AIRPLAftlEJVS n 
WAIT KEY 


Figure 2: Sim pie DVI video play 


Figure 3 shows the use of DPLAY after an AVC 
image is displayed with the SHOW command. 

The AVC image exists as an overlay on top of 
the video image; the story continues after a key 
is pressed. 


SHOW "C:\IMAGEACLOUD" (WAIT= 0} 

DPLAY "C:\VIDEO\AIRPLANEJVS" 

WAIT KEY 


Figure 3: Simple DVI video play, overlay with image 


A partial AVC image or text can also be 
overlaid with DVI video by using the PASTE 
command. 


DSHOW for DVI still images has syntax similar to 
that of DPLAY. Specify the name of a DVI still file 
following the DSHOW, Any of the acceptable still 
file types can be used. 

DCDNFIG controls the DVI playing configuration, 
including: 

* Resolution sets screen resolution to either 
512x480 or 256x240. 

* Speed controls video play speed. 

* Monitor controls monitor use, DVI and 
VGA/XGA image can be merged on one 
monitor or viewed on two separate 
monitors. 


Since the AVA 
language is 
interpretive, 
AVC story 
writers can 
create and 
modify their 
presentations 
interactively. 


* Volume controls audio volume. 


• Balance controls audio balance between left 
and right channels. 

* A_V selects presentation of video, audio, or 
both. 
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• Erase determines whether a previously 
displayed DVT file image is erased from the 
screen when new images appear. 

• Contrast adjusts the monitor contrast for DVl 
images. 


• Brightness adjusts monitor brightness for DVI 
images. 

Figure 4 shows fade-in during a DPLAY, using 
the manipulation of contrast and saturation in 
a DO-LOOP. 


• Saturation adjusts monitor saturation for DVI 
images. 

• Tint adjusts monitor tint for DVI images. 


DCOJVFIG CDIil (-100) 

/* 

Initial contrast at -100 

DCONFIG SAT (-100) 

/* 

Initial saturation at -100 

DPLAY "C:\VIDE0. A VS 11 

/* 

Start video 

Do i = -100 to 0 

/* 

Fade-in video 

DCONFIG CON i 

/* 

change of contrast 

DCONFIG SAT i 

h 

change of saturation 

WAIT .1 



END 




Figure 4: Fade-in video 


DPLAY "C:\AIRPLANE.AVS" 


Do until &DSTATUS=$TDP 

/* Query for status during the 

DfJUERY 

/* the entire play 

say "Frame no.= "ftdFrame 

/* Display known frame number 

WAIT .1 


End 



Figure 5: Use of oqUERV 


DQUERY returns the current frame number and 
play status in the AVA variables; 0DFRAME: 
returns the current frame number and 
ODSTATUS: shows player status—STOP, PAUSE, PLAY, 
or ERROR. 

In Figure 5, DQUERY is used to display frame 
numbers during video playback. 

DLOCATE defines winch part of a DVI source 
image to display as well as the size and 
location of the display area for the target 
image. Stills and video clips can be controlled 
by DLOCATE. DLOCATE S controls the image or 
video source; DLOCATE T controls the display 
target area. 

The screen is divided into coordinate space of 
100x100. The four parameters (x, y, dx, and dy) 
following DLOCATE S or DLOCATE T refer to the 
upper left coordinates, width, and height of 
the display area. 

Combined application of DLOCATE S and 
DLOCATE T can create many interesting display 
schemes for video and still images. Figures 6 
and 7 give simple examples. 


DLOCATE S 0 0 100 100 

/* Default full size source 

DLOCATE S 25 25 50 50 

/* Middle quarter of the source 

DLOCATE T 0 0 100 100 

/* Default fun screen target 

DLOCATE T 25 25 50 50 

/* Display in the middle quarter 
/* of the screen 

DO 1=0 to 50 

DLOCATE T i i 100-i-i 

100-i-i /* Shrink the target video 

WAIT .1 

/* from full screen 

END 

/* to a single dot 

DO i - 0 to 50 

DLOCATE T i ((i-50)*(i-50)}/25 i i /* curved path of 

WAIT .1 

END 

/* target rectangle 


Figure 6: Various use of DLOCATE for display areas 


SAMPLE MACROS FOR VARIOUS 
PRESENTATION EFFECTS 

AVA's macro routine calls can be used to write 
interesting video and still image display, 
transition, or dissolve methods. This section 
presents additional examples for beginning 
AVC users. 

In Figure 8, DVI still or video images are 
displayed in an array of small rectangles, each 
one-tenth the width and height of the screen. 

Figure 9 shows the display transition routines 
SweepH, FlipH, SweepV, and FlipV. 

A still image Stilll is shown in the middle of 
the screen. Still2 is then superimposed with the 
horizontal sweeping-across routine, followed 
by image StiU3 with the horizontal page- 
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Figure 7 1 last example in Figure 6, curved display path 


flipping routine. Users can construct other 
methods such as vertical sweeping and 
flipping, band-sweeping, and tile-filling. These 
display transition methods can also be applied 
to video using DPLAY. 

In general, the video DPLAY instruction is 
asynchronous and interruptible. While the 
video is run, the story is controlled by 
instructions such as SHOW, PASTE, PLAY, DLOCATE, 
DCONfIG, and OQUERY. The computer switches 
automatically between playing the video and 
running the other instructions. If the other 
instructions monopolize computer time, they 
could affect video synchronization. The video 
will be out of sync if given an insufficient time 
share. Instructions such as WAIT can be used to 
pace story flow and video run time. There is 
also a synchronous option to launch the video 
clips in the stories. 

NEW METHODS OF 
COMMUNICATION 

AVC support for DVI is built with the Audio 
Video Kernel (AVK), which is designed to 
work with future digital video hardware 
releases. AVK is being updated for OS/2 2.0, 
Microsoft Windows, and higher-level 


multimedia operating system extensions. AVC 
written with AVK is in a stable environment 
and the porting path to other operating 
systems' extensions is relatively easy. 

AVC addresses the main requirements of 
multimedia applications. With digital video 
storage and networking, applications built 
with AVC can be effectively customized, 
updated, and revised, leading to the 
flourishing of multimedia applications for 
business, travel, merchandising, 
manufacturing, entertainment, and education. 


CALL GRID10 OSHOW "0:STILLJVS" 
CALL GRID10 DPLAY "D:VIDEOJYS" 


GridlO: 

DLOCATE T 0 0 10 10 
JtRGCl) ARG(2) 

DO j = 0 to 9 
DO i = 0 to 9 

DLOCATE T i*10 j*10 10 10 
END 
END 

RETURN 


Figure 8: GRtDIO: Multiple display in an array of WxtO 
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QUOTE T 25 25 50 50 

DSHOW Stiill 

wait 1 

CALL SweepM DSHOW $till2 
wait 1 

CALL FlipH DSH0W 5tiH3 
wait 1 

/* Display Still! in the middle 
/* quarter of the screen 

/* Replacing by Still2 with 
/* horizontal sweep 

/* Replacing by $tiH3 with 
/* horizontal flip 

SweepH: 

DLOCATE T 25 25 0 50 
DLOCATE S 0 0 0 100 

ARG(l) ARC{2) 

DO i = 0 to 50 by 5 
DLOCATE T 25 25 i 50 
DLOCATE S 0 0 i+i 100 
WATT .1 

END 

RETURN 

/* Horizontal Sweep 

FlipH: 

DLOCATE $ 0 0 100 100 
DLOCATE T 25 25 0 50 

ARG(l) ARG(2) 

DO i - 0 to 50 

DLOCATE T 25 25 i 50 
WAIT .1 

END 

RETURN 

/* Horizontal Flip 

SweepV: 

DLOCATE T 25 25 50 0 
DLOCATE S 0 0 100 0 

ARG(l) ARG{2) 

DO i - 0 to 50 by 5 

/* Vertical Sweep 


DLOCATE T 25 25 50 i 
DLOCATE S 0 0 100 in 
WAIT A 
END 
RETURN 


Flip V: 

DLOCATE S 0 0 100 100 
DLOCATE T 25 25 50 0 

ARG(l) ARG(2) 

DO i = 0 to 50 

DLOCATE T 25 25 50 i 

WAIT .1 

END 

RETURN 

/* Vertical Flip 


Figure 9; SveepH, Flip! Sweeps FlipV: display transition examples 
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Multimedia and Graphics 

Listen to the Sounds: 
_ Audio Subsystem 



Chris Dirntlo 


by Chris DirnUo 

The Multimedia Presentation Manager/2 Audio 
Subsystem™ (MMPM/Z) enables a PC to play ami 
record audio waveform and MIDI data . 


ANALOG VS. DIGITAL AUDIO 

A nalog audio, used in devices such as 

radios, tape decks, and microphones, is 
concerned with the generation, transmission, 
and reception of sound waves. These waves 
are characterized by amplitude, wavelength, 
and frequency, A sound wave's amplitude is 
measured by the amount, or volume, of 
atmospheric pressure it displaces. A 
wavelength is the distance sound travels 
during one complete cycle of pressure change, 
while frequency is the number of times a wave 
cycles per second. A high frequency (many 


Wavelength is constant 



TIME 


Figure V Sound zwivc characteristics. Amplitude decreases in tmicas wavelength 
remains constant, 
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cycles) produces a richer, more audible sound. 
Figure 1 illustrates the characteristics of a 
sound wave. 

In contrast to analog audio, digital audio is a 
study of discrete values. Digital audio records 
the same sound characteristics as analog 
audio, but catalogues each discrete moment 
with nonvarying precision. Digital computer 
techniques make it possible to generate, 
transmit, and receiv e digital audio with no loss 
of information. Because it is comprised of 
digital data, digital audio is not affected by 
outside factors, and therefore provides 
consistently repeatable sound reproduction. 
Compact discs (CDs) and CD players, the most 
common digital audio formats, bring high 
sound quality and absolute repeatability to the 
home stereo. 

An alternate form of digital data that produces 
audio is called MIDI, or Musical Instrument 
Digital Interface. MIDI is digital protocol that 
is translated by synthesizers and musical 
instruments into waveform output. 

With the technology of MMPM/2, PCs can 
now' interact with digital and MIDI audio 
systems for recording and playback. The 
subsystem even has a built-in music 
synthesizer that enables the user to play MIDI 
data without MIDI instruments, providing a 
cost-effective entry point into the MIDI 
environment; 


SOUND FLEXIBILITY 

Hardware configurations for the Audio 
Subsystem can include an audio adapter (for 
example, IBM's M-Audio™), CD-ROMs, 
compact disc-extended architecture (CD/XA), 
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and additional stereo equipment such as 
receivers and audio tape decks. One possible 
setup is shown in Figure 2, 

The software for this setup is IBM's MM PM/2, 
an OS/2 2.0 multimedia subsystem made up 
of several code modules. Each module 
performs a specific function and can be 
replaced by custom-built third-party modules 
(such as the WaveAudio™ media control 
driver (MCD), MIDI sequencer MCD, 
Amp/Mixer MCD, Audio Stream Handler 
device driver, and M-Audio physical device 
driver) as long as these modules conform to 
MMPM/2 API interfaces. 


A SOUND ARCHITECTURE 

The MM PM / 2 API interfaces consist of three 
layers: the Media Control Interface (MCI), the 
Streaming Protocol Interface (SPI), and the 
physical Device Drivers (PDDs). The three 
layers span OS/2's rings, with the media 
control drivers (MCDs) existing as ring 3 DLLs 
and the stream handlers existing as either ring 
3 DLLs or (as in the Audio Stream Handler) 
ring 0 device drivers. This setup is shown in 
Figure 3. 

A typical application would use the MCI to 
command the subsystem. Its functions include 
playback and record of audio data types and 
user controls such as volume, bass, and treble. 
The residing modules are DLLs (WaveAudio, 
MIDI Sequencer, and Amp/Mixer). In Figure 
4, an application requests audio playback. 

The SPI, primarily used by the Audio 
Subsystem's MCDs, controls data flow (which 
may consist of pulse code modulation (PCM), 
adaptive delta pulse code modulation 
(ADPCM), CD digital audio (CD-DA), 

CD/XA, and MIDI) to and from the audio 
device. The MCDs request data and specify 
when it is to be moved, request cue-points, 
and have event call-back routines. Cue-points, 
which act as place holders within the media, 
can be represented as time elapsed (for 
example, 30 seconds into a specific piece) or as 
a recurrent value (for example, every second 
throughout the piece). Cue-point notification is 
initiated during stream creation, with the 
MCD's registration of the event callback 
routine. Figure 5 illustrates how an application 
requests a cue-point. 


On the receiving end of the SPI interface, 
stream handlers field SPI requests, control data 
flow, and monitor synchronization and cue- 
point detection. In Figure 6, an application or 
MCD initiates audio playback. 

The third API level is the device drivers. The 
foundation of the audio subsystem, it allows 
communication from MCDs via standardized 
fOCTL calls, which instruct it to set up the 
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- 


fVIIDI Synthesizer 


Speaker 


T igure 2: Multimedia hardware configuration options 



Figure 3: MMPM/2 Audio Subsystem modules within the three layers of APIs 
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HCI_0PEN_P ARMS mciOpen; 

HCIJPEN.LDAO mciLoad; 

MCI_PQY_PARN$ mciPiay; 

DWORD dwError; 

HWND hwndMyWindow; 

mciOpeiudwCallback = NULL; 

mciOpen.dwDevicelD = NULL; /* this is returned */ 

mciQperulpstrDeviceType = (LPSTR)NULL; /* default connection*/ 
rnciQperi.lpstrElementMame = lpstrElementName; 

dwError = mci$endCornrnand( (WORD) 0, 

MCI_0PEN, 

MCI.WAIT | MCI.OPEN.ELEMENT I 
MCI_DPEN_SHAREABLE I MCI_READONLY, 

(DWORD) &mciQpen, 

UP.OPEN); 

if (dwError) 

Abort(dwError); 

mciLoad,dwtallback = (DWORD) NULL; /* We're waiting */ 

mciLoad.lpstrElementName = lpstrElementName; 

dwError = mciSendCommarid{ mciOpen.dwDevicelD, 

HCI.LOAD, 

MCIJHIT | HCI_READONLY, 

(DWORD) ftmciLoad, 

(DWORD) NULL); 

if (dwError) 

Abort(dwError); 


mciPlay *dwCallbaek = (DWORD) hwndMyWindow; 
dwError = mciSendConnandf mciOpen.dwDevicelD, 

MCI_PLAY > 
MCIJOTIFY, 

(DWORD) ftmciPlay, 
UP_PLAY); 


Figure 4: Using MCI to 'open load and play an audio file 

audio adapter tor specific requests. The device 
driver facilitates communication between the 
API and SPI, binding the "streaming" of audio 
data to the physical device driver and then to 
the audio adapter. The communication 
interface consists of device driver commands 
(DDCMD) and stream helper function (SHF) 
APIs, DDCMD APIs are used to make requests 
from SPI stream handlers to the physical 
device drivers, and SHD APIs are used by 


physical device drivers to cal) back into the 
stream handlers. Figure 7 shows 
communication between the stream handler 
and the physical device driver. 

A SOUND INVESTMENT 

In any of the three layers of the API, hardware 
and software can be replaced by third-party 
modules. With this flexibility, the MMPM/2 
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/* Set a cuepoint at the 30 second mark in the media */ 

WORD wDevicelD; 

HWND hwndMyWindow; 

H CI.CUEPOIN T_ FIRMS CuePointParms 

/* assign dwCallback the handle to the PM Window 

this will be used for returning MM_HCICUEP0INT messages */ 

CuePointParms.dwCallback = (DVQRD)hvndNyWindov; 

CuePointParms.dvCuepoint = (DW0R0)90000; /* mmtirne format */ 

mciSendCommandtwDevicelD, /* device id */ 

HCI_SET_CUEPOINT, /* MCI message */ 

MCI_SET_CUEPOINT_ON, /* flags */ 

(DWORD) ^CuePointParms, /* data struct */ 

0); /* no user parms*/ 


Figure 5: Using MCI to set cuepomts 



spcbkey.ulDataType = DATATYPE.WAVEFGRM; 


spcbkey.ulDataSubType - WAYE_FDRMAT_2S08; 

/* 22kHz 8bit stereo */ 

spcbkey.ulIntKey = 0; 

/* no internal key */ 

strcpytdcb.szDevName, AUDI0O1$ ); 

/* device name to use*/ 

dcb.ulSysFileNum = ulSysFileNurn; 
pdcblgt = (PDC8)&dcb; 

/* from AUDIO.INIT I0CTL 

SpiCreateStrearn(hidSource, 

/* Source handler id */ 

hidTarget, 

1* Target handler id */ 

Aspcbkey, 

/* stream protocol */ 

NULL, 

/* Src DCB */ 

pdcbTgt, 

/* Tgt DCB */ 

&evcb. 

/* event control blk */ 

(PEVFN) MyEventRtn, 

/* addr of event rtn */ 

0, 

/* not a split stream*/ 

fthStream, 

/* hndl returned */ 

fchEvent); 

i* hndl returned */ 

/* Use MMI0 to get audio file and fill in 

ACB structure */ 

/* Next, make association of audio file to stream created */ 

SpiAssociate(hStream, hidSource, (PACB)fcacb); 

/* Start playback of stream by issuing SpiStartStreamQ */ 

SpiStartStrearrKhStream, SPI_START_STREAM); 


/* Audio will play until end of stream, at which time 

the registered event routine will be called. */ 


Figure 6: Using 5PI to create an audio stream for playback 
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DDCMDREGISTER DOCHDRegister; 

PDCBJUDIQSN pDCB; 


/* Stream Handier to register a stream with the physical DD. 

*/ 

/* Get device info and attach to the audio PDD via OevHIp 

*/ 

if (DevHlp_AttachDD(nszAudioDDName, ^AttachAudio)) { 
return(ERROR_DEVICE JOT.FOUND); 

> 


/* make a 16:16 pointer to call PDD 

*/ 

pSTREAM->pDDCMDEntry Point = (PDDCMDFN)HAKEP{AttachAudio.protCS, 

Attach A ud±o.protO FF); 

DDCMORegister.ulFunction = DDCMD_REG_STREAM; 
DDCMMegister,hStreafn = pSTR£AM->hStream; 

DOCHDRegister.ulSysFileMum = pDCB->ulSy$FileNum; 
DOCHDRegister.pSHDEntryPoint = PSHDEntryPoint; 

DOCHDRegister.ulStreamOperation = SIREAM_OPERATION_PRDDUCEi 


DOCHDRegister.spcbkey.ulDatalype = pCreate->spcbkey.ulDataType ; 

DOCHDRegister.spcbkey.ulDataSubT ype=C reate->spcbkey, ulOataSubly pe; 

DOCHDRegister.ulBufSize = 0; 

DOCHDRegister,ulftlumBufs = 0; 

DOCHDRegister,ulBytesPerUnit = 0; 

DDCMDRegister.mmtimePerUnit = 0; 

DOCHDRegister.ulAddressType * ADDRESSJYPE.PHYSICAL; 
rc = (*pSTREAM->pDDCHDEntryPoint}(^DDCMDRegister); 


/* Physical device driver calling Stream Handler during interrupt time */ 

SHD.REPORTINT Shdlnt ; 


Shdlnt.ulFunction = SHD_REP0RT_INT ; /* report interrupt */ 

Shdlnt.hStream = pStream->hStream; /* stream hndl 

*/ 

Shdlnt.ulFlag = SHD^WRIFE.COMPLETE; /* function done 

*/ 

Shdlnt,uTStatus - ulBytesPlayed; /* # of bytes written*/ 

Shdlnt.ulStreamTime = uHncrementalTime; /* millsec time 

*/ 

((PSHDFN)pStream->ADSHEntry)(&ShdInt); /* IDC call to SH 

*/ 


Figure 7: Using DDCMDs and SHDsfor Inter-Device Driver Communication (IDO 


architecture will be able to incorporate future 
advances in technology and protect customer 
investments well into the future. 

MMPM/2's ability to process many sounds at 
various quality levels while providing a 
flexible hardware and software environment 
can transform a PC into a personal multimedia 
entertainment center or recording studio with 
much potential for growth. 


Chris Dinallo, IBM Corp., Personal Systems 
Programming , P.O. Box 1328 Boca Raton, Fla., 
33429. Dinallo is a staff programmer in the 
Multimedia Software Development department and 
is the lead developer of the MMPM/2 Audio 
Subsystem . He has worked in Multimedia Software 
since its inception in March 1990. His prior 
experience includes firmware and DOS kernel 
programming , Dinallo has a BS> in computer 
science from the University of Florida. 
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Database Manager 

Advanced Programming 
Considerations for 
Database Manager 



by Lance Amundsen ami Richard Hoffman 

Database design and development are driven by 
factors such as normalization, integrity constraints, 
ami DASD requirements. Programming guidelines 
are often affected by concerns about portability or 
by the need to maximize use of existing code . On 
the other hand , performance ami ease of use are 
prime concerns for those who must use a database 
application day to day, long after design and coding 
is done. 

This article focuses on features unique to Database 
Manager that can be used to enhance application 
performance and improve application usability. 
These features include locking options, static vs. 
dynamic SQL usage, and record blocking. 

LOCKING OPTIONS 

ost databases accessed by multiple 
users have some method of locking to 
avoid modification anomalies. Locking, 
however, can decrease concurrency, the ability 
of mutiple users to efficiently update the 
database at the same time. Locking can also 
degrade performance, especially when locking 
"granularity" is increased. 

Figure 1 shows the tradeoff between 
performance and concurrency as a function of 
locking granularity. 


Repeatable Read 

As they are fetched for a cursor, rows are 
locked and remain locked until the end of a 
transaction, thus producing a "repeatable 
read" cursor. For example, as rows are fetched 
for a cursor that references "all employees 
with salaries greater than $30,000/' each row is 
locked. Repeatable read ensures that the next 
time the cursor is opened and read within the 
same transaction, those rows of the cursor will 
be unchanged by other applications or 
processes. 

Row-level locking under repeatable-read 
isolation is supported only if the data is 
accessed with an index. If a table scan is used, 
the entire table is then locked. 

Cursor Stability 

The currently accessed row of a cursor and 
previously changed rows in the same 
transaction are locked. When a cursor is 
processed using FETCH statements, cursor 
stability ensures that any fetched row is 
locked, until the next FETCH statement is 
processed. This allows an application to 
retrieve, examine, and change a single row 
without another application or process 
modifying that row. 

Uncommitted Read 




htnce Amundsen 



Richard Hoffman 


ISOLATION LEVELS 

Database Manager uses the isolation level 
option to determine the basic locking scheme 
for cursors in an application. Three isolation 
levels are offered for Database Manager 
applications. 


No row locks are acquired or examined. This 
isolation level is used for cursors that read data 
without updates. However, because 
uncommitted read cursors do not examine 
locks, it is possible to read the uncommitted 
data of other applications. This uncommitted 
data might not be valid, because another 
application's transaction could eventually be 
rolled back instead of committed. 
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Because uncommitted read, or "dirty read," 
cursors cannot be used to update a database, 
this isolation level applies only to the "read¬ 
only" cursors in an application. Cursors that 
can be updated function as if the cursor 
stability isolation level were in effect 

LOCK TABLE STATEMENT 

If an application requires more explicit control 
over locking, the SQL statement LOCK TABLE can 
be used to lock an entire table in either 
EXCLUSIVE or SHARED mode. 


Row Locks 



Table Locks 


Figure l: Performance and concurrency imations due to changes in locking 
granularity 

SHARED mode allows other applications to read 
data in the locked table, but not to modify that 
data, while EXLUSIVE mode prohibits updates 
and reads by other applications, except for 
those using the uncommitted-read isolation 
level. 


DATABASE CONFIGURATION 
PARAMETERS RELATED TO 
LOCKING 

Parameters in the database configuration file 
associated with each database can affect 
locking performance. The two most important 
are LOCKLIST and MAXLOCKS, 

Lockiist 

The size of the lock list Database Manager 
stores in memory for all applications accessing 
the database. This value is specified in 4K 
pages, with betw een 80 and 160 locks allowed 
per page. The range of values allowed is 4 to 
250 with a default of 8, 

Maxlocks 

Maxlocks refers to the percentage of LOCKLIST 
an application can use before escalation. 
Escalation is the process of converting the row¬ 
locks of the application's most locked table to 
an explicit table lock. 

With escalation, concurrency decreases and 
the benefits of row-level locking start to 
disappear. It is therefore important to 
minimize escalation by choosing a large 
enough value for LOCKLIST (25 is a good starting 
point) and by carefully controlling COMMIT 
points within the application to ensure that it 
acquires no more locks than allowed by the 
MAXLOCKS percentage. 

LOCKING TIPS AND STRATEGIES 

Repea table-read applications accessing a large 
percentage of the rows in a table can often 
benefit by a LOCK TABLE statement. The overhead 
of invidual row locks is eliminated with, in 
some cases, only a minor reduction in 
concurrency. 

Table locks can be automatically acquired by 
Database Manager when lock escalation occurs 
or w'hen a table scan is used to access a 
repeatable read cursor. To avoid unwarranted 
table locks and increase concurrency, avoid 
escalation and access repeatable read cursors 
via an index. The Database Manager EXPLAIN 
utility can be especially helpful for 
determining the access method used by 
Database Manager. 
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When not updating data, consider the 
uncommitted-read option. Although this 
maximizes performance and concurrency, you 
must remember the implications of reading 
uncommitted data. 


SQL statement text can be generated at run 
time. Preparation time can be significant, 
however, and can hurt performance. 

Persistence 



Don't overlook the uncommitted read option 
when updating data, especially if you make 
infrequent changes. It is possible to read data 
and then issue an explicit searched update for 
a record. A unique Held such as a timestamp is 
especially helpful in this situation. Even 
without one, the WHERE clause of the UPDATE 
statement could contain sufficient information 
to guarantee that another application hasn't 
changed the record since it was last read. 
Without a timestamp, however, the entire 
record might have to be specified in the WHERE 
clause, and duplicate rows could present a 
problem. 


STATIC VS* DYNAMIC SQL USAGE 

Database Manager provides both static and 
dynamic SQL. Static SQL increases 
performance while dynamic SQL allows 
greater flexibility. Figure 2 shows the major 
differences between static and dynamic SQL. 


DIFFERENCES BETWEEN 
STATIC AND DYNAMIC SQL 

Preparation 

The preparation of an SQL statement imioves 
parsing and syntactic and semantic checking 
of the statement text, followed by an 
optimization step that determines how to 
efficiently access data. An executable form of 
the statement is then created. 

For static SQL, this step is performed at 
precompile time and optionally repeated at 
later bind times. The executable form is stored 
in a package, or access plan, in the database. 
One restriction of static SQL is that complete 
statement syntax must be specified at 
precompile time. Host variables can substitute 
values at run time, but the statement must 
reference only existing objects. 


The persistence of an SQL statement is the life 
of the executable form of the statement, or the 
length of time between a statement's 
preparation and the need for subsequent 
preparation. 

For static SQL, the executable form lasts as 
long as the database package that contains it 
lasts, or until a new executable form replaces it 
during package regeneration, such as when 
the application is rebound. 

For dynamic SQL, the executable forms lasts 
only as long as the transaction. A dynamic 
SQL statement must be reprepared after a 
COMMIT or ROLLBACK. The one exception to this 
rule is for cursors declared WITH HOLD. Unlike a 
ROLLBACK, a COMMIT does not destroy a dynamic 
WITH HOLD cursor or any dynamic statements 
associated with it 


Item 

Static SQL 

Dynamic SQL 

Preparation 

At application 
development time 

At run time 

Persistence 

Until rebound 

For the duration 
of the transaction 

Authorization 

Binder 

User 

Optimization 

Assumptions 

Those present 
at bind time 

Current 


Figure 2: Differences between static and dynamic SQL 


Authorization 

The authorizations required to process an SQL 
statement can be checked either at application 
bind time or at run time, with the fundamental 
difference being the authorities of the binder 
and user. 


For dynamic SQL, this step is performed on 
the fly, while the statement is executed by the 
user. One advantage of this setup is that the 


For static SQL, the authorization of the binder 
is used for all data manipulation SQL 
statements, but data definition statments use 
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The total time it 
takes to run a 
query is 
T = P + E, 
where P 
represents 
preparation time 
and E represents 
execution time. 


the authorization of the user. Users need only 
the EXECUTE privilege on the package to invoke 
any of the DML SQL statements in the 
program. One advantage to this is that a user 
can be restricted from full UPDATE privileges on 
a table while still being allowed to update that 
table using a limited number of static SQL 
statements contained in the application. 

For dynamic SQL, the user authorization is 
checked for all SQL statements. Each user 
must therefore have the required privileges to 
execute a SQL statement dynamically. 

Optimization Assumptions 

Optimization uses database statistics to 
determine an efficient way to access data. 

For static SQL, optimization uses the statistics 
present when the application is bound. These 
statistics, however, might or might not be an 
accurate respresentation of those that exist 
when the application is actually run. It is 
therefore important to periodically use the RUN 
STATISTICS function followed by rebinding all 
static SQL programs, especially when there are 
significant changes to the database. 

For dynamic SQL, the most recent statistics 
are always used. This can dramatically affect 
performance in some cases, such as when an 
index is added that could be taken advantage 
of by a dynamic query. The same static query 
couldn't incorporate this information without 
being rebound. 


THE BOTTOM LINE 

So what does all this mean? One thing to 
consider is that the total time it takes to run a 
query is T = P + E, where P represents 
preparation time and E represents execution 
time. 


run more quickly since more current 
optimization assumptions are used when the 
statement is prepared at run time. 

A further consideration is that certain 
assumptions can be made for some dynamic 
SQL statements that can't be made for similar 
static SQL statemtents using host variables. 
One case of this is a dynamic query using a 
literal constant in a WHERE clause, instead of a 
static query that substitues the value in a host 
variable at rim time. 

For example, a complex query involving many 
joins containing a WHERE CQL greater than 100 
could be more efficiently optimized when the 
database statistics indicate that only a small 
number of rows, or no rows at all, satisfy the 
criteria. The join order would be performed to 
eliminate as many rows as possible as soon as 
possible. This information is not available to 
the optimizer, however, when the value in the 
WHERE clause is provided by a host variable at 
run time. 

Other examples can be found in which a 
dynamic form of a SQL statement executes 
much faster than a similar static statment. This 
is especially true for a WHERE clause containing a 
LIKE "string literal'' without a wildcard as the 
first character. An index on the column could 
be used, but not if a host variable substituted 
the value at run time. 

A final point to consider is the persistence of 
dynamic SQL statements. Every application 
must periodically issue COMMIT statements to 
maintain high concurrency and force physical 
writes of the database logs. This helps to avoid 
data loss in the event of a power failure. 
Dynamic statements must be reprepared after 
a COHHIT, which can take considerable time if 
done repetitively, such as in tight program 
loops. 
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If a query is complex but doesn't return many 
rows, P might be large compared to E. In this 
case, a static version of the SQL statement 
would run more quickly since the preparation 
time is performed at application development 
time instead of at run time. 

If a query isn't complex and returns many 
rows, P might be small compared to E. Here, a 
dynamic version of the SQL statement could 


RECORD BLOCKING 

Consider the following scenario: an 
application displays 30 records at a time to a 
user browsing the data. The data is located on 
a server on a busy network; response time can 
be as high as half a second. Each time the user 
pages down, the application issues another 30 
FETCH statements, each of which taking up to 
half a second to process remotely. The total 
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time elapsed between screens of information 
could be as high as 15 seconds. 

Although hypothetical, this example points 
out that network transfer time is not negligible 
and can make up a significant percentage of 
total processing time. 

A faster approach might be to return a block of 
rows. The susbsequent FETCHes would occur 
locally, reducing network traffic from 30 
requests to as few as one. This is where record 
blocking comes in; Database Manager allows 
read-only cursors to be blocked, as in Figure 3. 

With record blocking in effect, the first FETCH 
for a cursor causes a block of rows to be sent to 
the client. Subsequent FETCHes retrieve data 
from a local buffer in which Database Manager 
has automatically allocated and stored the 
block of rows. When all rows from the block 
are retrieved, another block is sent to the client. 

All this activity is transparent to the 
application except for the increased 
performance and the difference between the 
"Virtual" cursor position and the "actual" 
cursor position. On the first FETCH, the 
application is positioned on the first row. The 
cursor position at the server, however, is 
different. The actual cursor is located on the 
row first returned with the next block of rows. 

This situation leads to the restriction that 
blocked cursors cannot be updated. Tills is 
because the row an application is examining is 
not the "actual" cursor position and is 
therefore unlocked. Other applications might 
have modified the row between the time the 
block of rows was sent to the client and the 
time the client actually fetched the row. 


BLOCKING OPTIONS AND 
AMBIGUOUS CURSORS 

Record blocking is automatically enabled by a 
precompile and bind option. The /K option can 
be specified as follows: 

* /K=ND —Do not block any cursors 

* /K s UNAMBIG —Block all cursors known to be 
read only 

* /K=ALL —Block cursors that are known to be 
read only and cursors that are ambiguous 


To define ambiguous cursors, consider that 
updates to a cursor cannot occur if the cursor 
is based on a read-only SELECT statement, such 
as one referencing a nonupda table view or 
involving a UNION. 

Cursor updates cannot occur if the cursor 
involves a sort as with a SELECT statement 
involving a DISTINCT, ORDER BY, or GROUP BY 
clause, or if the cursor is declared FOR FETCH 
ONLY. 

On the other hand. Database Manager 
assumes that updates will occur if the cursor is 
declared with a FOR UPDATE clause, or if a DELETE 
or UPDATE WHERE CURRENT OF statement ls 
associated with the cursor. 



CLIENT SERVER 


-► 

virtual 

cursor 

position 


4 - 

(block) 


4 - 

actual 

cursor 

position 


Row 40 


Row 40 


Row t 


Row 1 

Row 2 

FETCH 

Row 2 


Figure 3: Blocking read-only cursors 


If neither of the previous situations is true, the 
cursor is assumed to be read only unless a 
PREPARE, EKECUTE, or EXECUTE IMMEDIATE statement 
appears in the same source file of the 
application. In this situation, a dynamic SQL 
statement that updates the cursor, such as 
DELETE WHERE CURRENT OF, could be executed. This 
is called an ambiguous cursor. 

Ambiguous cursors are not blocked if the 
default blocking option, /KHINAMBIG, is used. 
They are blocked, however, if the /K=ALL option 
is used. Since data integrity is so important, 
any update attempt against a blocked cursor 
will return an error. 


107 



























IBM OS/2 Developer 



BLOCKING PARAMETERS 

The following Database Manager 
Configuration File parameters affect blocking 
performance: 

* SVRIQBU indicates the maximum size of the 
block of rows the server can send to the 
client when a blocked cursor is fetched. This 
value ranges from 4K to 64K. 

* RQRIOBLK indicates the size of the block of 
rows an OS/2 database client requests when 
a blocked cursor is fetched. This value 
ranges from 4K to 32K, with a default of 4K. 



main 


call 

call 

call 

Spreadsheet 

Update 

Browse 


i i i 


EXEC SQL 


EXEC SQL 

■"1 


EXEC SQL 

(static) 


(stat+dynam) 


(dynamic) 



i 

PLAN S: 


PLAN U: 


PLAN B: 

BLK^ISIONE 

I30=RR 


BLK=UNAMB 

ISO=CS 


BLK=ALL 

ISO-UR 


Figure 4: Application using multiple packages-, isolation levels, mid blocking option? 


* SQLSIZE indicates the size of the block of rows 
that DOS and Windows database clients 
request when a blocked cursor is fetched. 
This value ranges from 512B to 64K, with a 
default of IK. 

* COMHEAPSZ gives the size of the client 
communications heap for OS/2 database 
clients in 64K shared segments. Set this 
value to at least 1 + jn x RQRIQBLK / 64KB, 
where m is the number of open cursors for 
the application. 


* NUMRC indicates the number of 
communication heaps available at the server. 
If this value is exceeded, blocking is disabled 
for OS/2 database clients and a connection 
attempt is refused for DOS and Windows 
Database clients. 


MAXIMIZING RECORD 
BLOCKING 

To maximize record blocking, 

* Declare all read-only cursors as FOR FETCH 
ONLY. This completely eliminates ambiguity. 

* With high-volume, often-run queries, choose 
SVRIOBLK and RQRIOBLK to be as large a multiple 

of the row size as possible. 

* Do not mix static and dynamic SQL in the 
same source file unless ambiguous cursors 
can be tolerated (by using the /K=ALL option, 
for example). 

* Finally, bind or precompile with /K-ALL, 
unless updates or "true'' cursor stability are 
required. 


GOING ONE STEP FURTHER 

The record blocking feature of Database 
Manager does have some limitations. The 
parameters affecting record blocking are 
system wide, and the maximum amount of 
data that can be blocked is 32K for OS/2 
Database clients and 64K for DOS and 
Windows database clients. 

Fortunately, use of the Database Application 
Remote Interface feature (AR1) of Database 
Manager allows an application to be split into 
a client procedure running on the client and a 
sewer procedure stored on the database 
server. The server procedure runs at the 
database location and can return information, 
such as a block of rows, to the client. Server 
procedures can be tailored to the specific 
blocking needs of the application and are not 
subject to 32K and 64K blocking limits. 

Using ARI for custom record blocking is 
beyond the scope of this article, however; 
additional information can be found in the 
References box. 
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PUTTING IT ALL TOGETHER 

This article has covered a broad range of topics 
that can be combined in the same application. 
A single application can access multiple 
packages; each including static or dynamic 
SQL and with each package bound with 
different isolation levels and blocking options. 
Figure 4 shows how a single application can 
handle the needs of various application types* 

Spreadsheet 

This application displays more than a single 
row of information while allowing a user to 
browse and edit the data. The spreadsheet 
lends itself to static SQL; with a repeatable 
read isolation level to ensure that the all data 
examined by the user is locked. No record 
blocking is used; as updates are allowed. 

Single Record Update 

This application involves a single record 
retrieval based upon some criteria specified by 
the user, such as a name or employee ID. The 
user is then allowed to update the record. A 
combination of static SQL and the cursor 
stability isolation level works for this 
application; no blocking is used. A more 
complicated version would allow a user to 
enter an arbitrary query, defining a set of rows 
that could be examined and updated one at a 
time. Dynamic SQL works best here. 

Brorvse Only 

This application allows a user to specify an 
arbitrary query and to view but not change the 
resulting data. A dynamic SQL approach, with 
the uncommitted read isolation level and 
record blocking, gives optimal performance. 
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Database Manager 

User Exits: Using Nonstandard 
Devices with DBM 

You Can Back Up Your Database to Tape 


by Dawn E. Bezviner and Richard Lawrence 

The User Exit is a new feature of the OS/2 
Extended Services LG Database Manager (DBM) 
that allows yon to read and write to devices other 
than those supported by OS/2, With a User Exit , a 
database and its log files can he backed up to a 
nonstandard device (NSD) such as a tape unit , 
opticai disk, or host machine. This article describes 
how the User Exit benefits the database user and 
how it is used by DBM as well as offering some 
tips for writing one: 

There is a difference between a physical device and 
the software that drives it, Throughout this article 
each will be referred to as an NSD , since it should 
be clear from the context which is intended. Not all 
NSDs will be suitable for calling. Some advice for 
selecting one is included in this article. For a full 
description of the criteria for selecting an NSD f see 
IBM Extended Serv ices for OS/2 Guide to 
Database Manager, 

A User Exit is a user-supplied program that acts as 
a go-between for DBM and an NSD, Since the 
NSD is not supported by the underlying operating 
system, DBM cannot interact with it directly. 
Instead, it calls the User Exit , which in turn 
interacts with the NSD t The User Exit then returns 
to DBM, indicating whether or not an operation 
was a success . 


A User Exit can be called from two functions. The 
first is the DBM Backup and Restore function, 

DBM users had had a requirement to back up and 
restore databases to tape devices* Backing up a large 
database to disk is time-consuming and error-prone 
because of the large number of disks involved. Yet 
since DBM uses the OS/2 Backup and Restore 
functions, users were restricted to dances 
supported by OS/2: disks , hard disks , and LANs. 
Now the DBM Backup and Res to tb functions can he 
directed to call a User Exit , enabling the user to 
connect to an NSD . 

The second function that can call a User Exit is 
roll-forward recovery. Roll-forward recovery is a 
new feature that allows a database to be restored 
from a backup and brought up to a specific point in 
time by replaying the log files since that backup. An 
NSD is a logical place to store these log files. 

A CLOSER LOOK AT A USER EXIT 

F igure 1 shows how the DBM, User Exit 
and NSD interact. The DBM does not 
interact directly with the NSD at all; hence, 
neither DBM nor the database application 
needs to support the NSD, Several software 
products are available that support Backup and 
Restore functions between OS/2 and an NSD. 
When setting up a system, the database 



Figure h interaction between DBM. User Exit, and NSD 
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administrator chooses one, along with one of 
the NSDs it supports* Then the application 
writer writes a User Exit that interacts with 
DBM and the NSD. 

Let's look at the interfaces in Figure 1. First, we 
see the DBM calling the User Exit. DBM passes 
several different parameters, depending on 
which function is being called. The User Exit 
may support up to four functions: 

* Back up a database 

* Restore a database 

* Back up {or archive) a log file 

* Restore (or retrieve) a log file. 

The first parameter. Backup, Restore, Archive, or 
Retrieve, indicates which function is being 
called. (The functions will usually need to be 
written in pairs, Backup with Restore and Archive 
with Retrieve.) The other parameters specify 
the database to back up, the log file to archive, 
and the path of the log file. We will discuss 
these parameters later. {They are also 
described in depth in IBM Extended Services for 
OS/2 Guide to Database Manager *) 

The User Exit was designed to be flexible, and 
you should customize it according to the 
requirements of each database. For example, 
you might want to back up one database to an 
NSD and a second database to a different 
NSD. This tactic would also require that when 
the Restore function is called, you determine 
from which database to retrieve the 
information. To reduce wear on your tape 
device, try to archive several files at a time. 
Another good idea for handling log files is to 
compress them when archiving and 
decompress them when retrieving. For 
example, PKZ1P™ is a product, shipped with 
Extended Services TO, that compresses and 
decompresses files. A database installation 
might have two NSDs, one used only when 
the first is down or unusable. In this case, the 
User Exit must determine which NSD to use. 

The second interface in Figure 1 shows the 
User Exit interacting with the NSD, Some extra 
work must be done here by the User Exit, as 
different Backup and Restore products will want 
information passed to them in different ways. 
For example, the Mountain Networking 
Solutions™ tape software allows all 


information to be passed by either command 
line or previously written procedure. The 
Sytron SytosPlus™ tape software, on the other 
hand, requires most of the information to be 
specified in a previously written procedure 
and allows only limited changes through the 
command line. The User Exit must know the 
name of the procedure; DBM will not. The 
User Exit must translate all information from 
the form in which the DBM passes it to the 
form the particular product being called 
requires. Then, the User Exit does the actual 
invocation. 


RETURN CODE 

MEANING 

0 

Successful 

4 

A resource error occurred 

8 

Operator intervention is required 
(for example, drive door is open) 

12 

Hardware error occurred 

16 

Defect, configuration, or installation 
error occurred 

20 

Invalid parameter received 

24 

Required files not found 

28 

Unknown error occurred 

32 

Operator cancelled the function 


Table 1: Return codes 



The third interface shows the NSD returning 
to the User Exit, fn general, this will be a 
return code indicating whether or not the task 
was completed successfully. At this point, the 
User Exit can return to DBM, or it can do 
further processing and reinvoke an NSD. In 
the example where the database installation 
has two NSDs, one for use when the first is 
down, the User Exit should determine which 
NSD was called. If it was the first, the User 
Exit should do whatever processing is needed 
to call the second NSD and invoke it. 
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The fourth interface shows the User Exit 
returning to the DBM. DBM will handle any of 
nine return codes. Since the NSD is not likely 
to have the same set of return codes, the User 
Exit must map the NSD's return codes to an 
appropriate DBM return code. The nine return 
codes are shown in Table 1. 

The DBM uses the different return codes in 
two ways. The first way is to determine 
whether the operation was successful. (If a log 


/«*t*«******4#*******t********t MAPRC PROCEDURE ********************/ 

/* Check the return code from the MaynStream Tape Backup Software */ 

/* and it to the expected DBM return codes* 

*/ 

ill**********-*******************************##******* ***********/ 

maprc: 


Select 


when re - 0 then do 

/* Successful *1 

sqluexitrc - IBM_RC.DK; 


return; 


end 


OTHERWISE do 

1* UNKNOWN ERROR */ 

sqluexitrc = I8M_Rt.UNKNOWN; 


return; 


end 


end 


return 



Figure 2: Mapping return cades 


file was not archived successfully, the DBM 
will not erase it.) The second way is to let DBM 
decide whether it can continue making calls to 
the User Exit. For example, if operator 
intervention is required, then a future call 
might succeed. However, if a hardware error 
occurred, future calls will not succeed. Since 
the DBM should always pass valid parameters* 
a return code of 20 indicates a serious internal 
problem {or a bug in the User Exit's parameter 
checking). As an example. Figure 2 shows a 
sample of how return codes would be mapped 
for the Maynard Maynstream tape software 
The User Exit should also clean up any 
temporary files or directories it created before 
returning to the DBM. 

So far, it has been assumed that the User Exit is 
written as though no operator is present at the 


computer when it is running. Some database 
users might not have an operator on hand, for 
example, for running an overnight backup. If 
an operator is present, Figure 3 shows how he 
or she can interact with the User Exit. 

The operator generally does mil interact 
directly with DBM. Even when the DBM uses 
the OS/2 Backup or Restore function, it is that 
function, not the DBM, that prompts for drives 
that aren't ready, prompts for the next disk, or 
checks and prompts when the wrong disk is 
inserted. When a User Exit is in use, either it or 
the NSD driver has to do that prompting. 
Specific error conditions are discussed later. 

EXAMPLES 

We have mentioned several ways in which to 
customize the User Exit. This section will give 
several examples of how to code some 
common functions. The application writer 
looking for more complete examples can also 
look at the four sample User Exits shipped 
with Extended Services TO DBM* 

Figure 4 shows how a User Exit might direct 
different databases to different NSDs. Suppose 
one database is very large, and the second is 
fairly small. In the example the large database, 
called DBONE, is backed up to a tape device 
using the Mountain Networking Solutions 
tape software. The second database, called 
DBTWO, is compressed and backed up to a 
hard disk using PKZIF. 

Figure 5 shows how a User Exit might group 
log files before archiving them. Sy iron SyPlus 
allows only a limited amount of information to 
be passed via the command line, with the rest 
specified in a previously saved menu-driven 
procedure. In this example, the application 
writer has created and saved a procedure 
called "Archlogs" which writes all files in the 
COLLECT,LOG directory to the NSD, 

Here, the User Exit collects up lO five log files 
before calling the NSD. Each time the User Exit 
is called to archive a log file, it first copies it to 
another directory, called COLLECT*LOG, 
compressing the file as it does so* If the 
number of the log file is divisible by 5, the User 
Exit then calls the NSD to write out the files. If 
successful, it erases the files from the 
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COLLECT.LOG directory and returns a 
successful return code. However, if the log file 
number is not divisible by 5, the User Exit 
simply sends a successful return code to the 
DBM, without invoking the NSD. 

There is a risk involved in saving log files 
before writing them to the NSD. If the 
database crashes, it can be recovered only to 
the latest point in the saved log files. The User 
Exit can, and should, check for log files in the 
COLLECT.LOG directory if they are not 
retrievable from the NSD, but if the disk 
containing the COLLECT.LOG directory is 
lost, then so are those log files. Any database 
requiring up-to-the-minute recovery, then, 
should either not save log files in this way or 
should save them on a different disk from that 
containing the database—not just on a 
different portion of the same disk, but on a 
physically different disk. That way, if either 
the database disk or the log file disk is lost, the 
other still exists as a backup. 

Figure 6 shows how the User Exit might 
prompt an operator in order to request 
operator intervention on the NSD. 


SUPPORTED LANGUAGES 

All of the examples shown so far have been 
written in OS/2 REXX. The User Exit can be 
written in any language that is supported by 
OS/2, allows a variable number of parameters 
to be passed, and can handle the characters 
appropriately (for example, the backslash in 
the path). The DBM will call SQLUEXXT parml 
pa m2 ..and OS/2 will search the PATH for an 
executable file with that name. The extension 
could be CMD or .EXE. Figures 7 and 8 show 
code fragments for writing the User Exit in C. 

To create a User Exit using C, the application 
writer simply treats the parameters passed in 
from the DBM as NULL terminated strings. Since 
the parameters are passed to the OS/2 
command processor as command line 
arguments, each is referable via the built-in C 
pointer array argv[ ] . 

Table 2 shows how the parameters relate to the 
argv[ ] array for a specific Backup call. 

Figure 7 shows entry into the User Exit. It logs 
the parameters and then calls a subroutine. 
Backup, Restore, Archive, or Retrieve, depending 
on the function requested by DBM. 


The User Exit 
can be written in 
any language 
supported by 
OS/2 that allows 
a variable 
number of 
parameters to be 
passed and can 
handle the 
characters 
appropriately. 
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BACKUP.PROC: 

h NOTE: this routine assumes that the input parameters to the */ 
/* User Exit were parsed as follows: */ 
/* parse upper arg OPT PARM1 PARM2 PARM3 PARM4 FARMS */ 


DB_DRIVE = strip(PARMl) /* 
DBJAME = strip(PARM2) /* 
RESP.FILE = strip(PARM3) /* 
LABEL = strip(PARM4) /* 
MODE = strip(FARMS) /* 

if( DBJAME = 'DBQNE" ) then 
do 


ex* D: */ 
ex* DBOHE */ 
ex* D:\SQLDBDIR\SQL00001.BKP */ 
ex* DBQNE-684686581 */ 
ex* 1 */ 


/* Strip timestamp from the generic LABEL */ 
parse var LABEL * dbm_time 
/* Create a label for Mountain */ 


mtn_label = "DATABASE 080WE BACKUP : PART "MODE, 
' : TIMESTAMP = 'dbm.time 


/* Create the command line for Mountain, and put it into */ 

/* the response file */ 

ctl_line * ' /L'mtn_label' /A/D/C hr 

CALL lineout RESP.FILE, ctljine 

/* Call Mountain to backup database files */ 

'tape SBK fl'RESP.FILE 

call checkrc /* Check return code */ 

end 

else if( DBJAME = 'DBTWQ" ) then 
do 

rspline = linein( RESPJXLE ) /* Read from the response file */ 


/*******************************t****************************/ 

/* Only compress the database files. Do not compress the */ 
/* the single UIF file which is backed up during MODE 1* */ 

/i***************************^*^***************************/ 


iff MODE = '2' ) then 
do 

/* ZIP the requested files */ 

'PKZIP2 C:\DBTUO\DBTVO.ZIP' 'rspJLine 
call checkrc /* Check return code from PKZIP */ 

end 
else 
do 

/* XCOPY the requested file(s) */ 

'XCOPY 'r$p_line' C:\D8TW0' 

call checkrc /* Check return code from OS/2 */ 

end 
end 
else 

log_err( "Database name not recognized 11 ) 


Figure 4: Handling BACKUP for two different databases 
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ARCHIV.PRQC: 


/* NOTE: this routine assumes that the input parameters to the */ 
/* User Exit were parsed as follows: */ 
/* parse upper arg OPT PARM1 PARM2 PARH3 PARM4 PARMS */ 

DB_DRXVE = left(stripCPARHl), 1) /* Strip the colon, ex, C */ 
DBJAME = strip(PARM2) /* ex, DBONE */ 
LOG^PATH = strip(PARM3) /* ex, C:\DBL0GS */ 
LOG.FILE = strxp(PARM4) /* ex, SQL00012.LOG */ 


/* Strip the extension and replace it with ZIP */ 

ZIP_FILE = left(LOG.FILE, 9) 'ZIP' 

/* compress the logfile and move it to a holding directory */ 
'PKZIP2 C:\C0LLECT,LOGVZIP.FILE LQG.PATB'/'LOG.FILE 
call checkrc /* Check return code from PKZIP */ 

if sqluexitrc <> IBM.RC.OK then 
signal FINISH 

/* Archive if log number is divisible by 5 */ 

LOGNUM = right(PARM4, 1) 
if (LOGNUM = '5' I LOGHUH = '0') 
do 

'syplus M Archlogs" 

call checksyrc /* Check the rc from SYPLUS */ 

if sqluexitrc <> IBM_RC,QK then 
do 

/* erase the file, since it will be archived later */ 
'ERASE C:\C0LLECT.L0G\'ZIP.FILE '1>NUL 2>NUL' 
signal FINISH 
end 
else 
do 

/* clean up - erase files from holding directory */ 
'ERASE C:\CQLLECT.LDG\*.*' 
end 


figure 5: Grouping log files before archiving 



Figure 8 shows a simple subroutine for the 
Backup function. It parses the input parameters 
and calls the WSD, 

BACKUP AND RESTORE VS. 
ROLL-FORWARD RECOVERY 

Backup and Restore and roll-forward recovery 
use the User Exit in different ways due to 
various nuances in each function. 


Frequency of User Exit Use 

The first major difference to consider is how 
and when the User Exit is called. For Backup 
and Restore, the User Exit is called infrequently 
and on an application or operator basis. For 
roll-forward recovery, the User Exit is called 
frequently, at asynchronous times, and is 
enabled on a per database basis. 
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BUCKUP.PROC: 


/* NOTE: this routine assumes that the input parameters to the */ 
/* User Exit yere parsed as follows: */ 
/* parse upper arg OPT PARM1 PARM2 PAR«3 PARM4 PARKS *f 


DB.DRIVE = strip(PARHl) 

/* ex. 

D: 

*/ 

DBJUHE = strip(PARM2) 

/* ex. 

DBONE 

*/ 

RESP.FILE = strip(PARM3) 

/* ex. 

D:\SqiDBDIR\SOL00001.BKP 

*f 

LABEL = strip(PARM4) 

/* ex. 

DB0NE-6846865B1 

*/ 

MODE = strip(PARM5) 

/* ex. 

1 

*/ 


/* Strip timestamp from the generic LABEL */ 
parse war LABEL * dbm_tirie 

I* Create a label for Mountain */ 

mtn.label = DATABASE DBONE BACKUP : PART 'MODE, 

' : TIMESTAMP = 'dbm.time 

/* Create the command line for Mountain, and put it into */ 

/* the response file */ 

ctlJLine * ' /L'mtn.Xabel' /A/D/C/-V' 

CALL lineout RE$P_FILE, ctl.line 

continue - 'YES' 

/* Loop until either the Backup is successful, or the */ 

/* operator decides to terminate it. */ 

do while (continue = 'YES') 

/* Call Mountain to backup database files */ 

'tape SBK OESP.FILE 

if( rc <> 0 ) then 
do 

say 'The Backup to the Mountain tape device failed 
say 'The return code was 'rc 

say 'Do you wish to attempt the Backup again (Y/N)' 
pull answer 

do while (answer <> 'Y') & (answer <> 'N') 
say '"Y" or "IT only:' 
pull answer 
end 

if( answer = 'N' ) then /* Operator cancelled retry */ 

continue = 'NO' 
end 
else 

continue = 'NO' /* Successful backup */ 

end 


Figure 6: Prompting the operator for error handling 
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This difference has several implications. First, 
if the User Exit is called for Backup or Restore, 
there will always be an application or operator 
to receive a return code. The application can 
check the return code and take appropriate 
action if the function fails. On the other hand, 
the User Exit calls for roll-forward recovery are 
asynchronous. An application may be doing a 
query when a problem arises with a User Exit 
call; the query should not fail because the User 
Exit failed. These problems are handled in two 
ways. If the failure occurs during an Archive 
call, the DBM will take no further action on the 
call The User Exit should log the failure and 
inform the operator immediately. It should 
then return the failure to the DBM, so the DBM 
knows not to erase the log file. If the failure 
occurs during a Retrieve call, the DBM will 
display a message on the screen. In this case, 
the User Exit does not need to inform the 
operator unless an immediate retry is desirable 
or necessary. The only exception is that if the 
SQLUEXIT executable is not found for either 
Archive or Retrieve, the DBM will display a 
message on the screen. 

The media used, combined with the way the 
User Exit is called, may have an effect on 
system performance. If the User Exit sends 
data to or from a hard disk, there is little 
performance impact. While hard disks are fast 
devices designed for frequent reads and 
writes, tape devices are much slower and 
largely used for infrequent reads and writes. 
Similarly, Backup and Restore cause a large 
amount of data to be read, written, and stored, 
while roll-forward recovery necessitates that 
only small amounts of data (for example, a log 
file) be read or written. If the database is 
modified often enough, and the log file is too 
small, then it is possible to overrun the tape 
unit. Tapes also have a shorter read and write 
life than hard disks. When configuring the log 
files and selecting a device and tape size for 
roll-forward recovery, an adminstrator should 
estimate how many log files will fit on the tape 
and determine whether the tape is capable of 
holding up under the expected wear and tear. 
The choice of peripheral used for archiving 
data, tape versus optical disk, and so on, will 
be in part a function of all the preceding 
considerations. 


Grouped vs. Stand-Alone Calls 

A second difference to consider is that the User 
Exit is called twice in a row for Backup and 
Restore. The backed up data should be kept 
together rather than divided between tapes. If 
the second call fails, the entire operation fails; 
if either dataset is lost, the Restore will fail. 

With roll-forward recovery, each call stands 
alone. Allowing a Backup to be divided across 
media requires that the programmer create a 
User Exit that is able to handle prompting. The 
user must then do more media management 
than merely sequencing tapes. In 
environments with more than one database 
backed up to the same device, it is 
recommended that the programmer ensure 
that no two database backups are allowed to 
go to the same tape or intertwine on a device. 
You can use the mode parameter to check for 
and prevent this condition. 



ARGV 

MEANING 

SAMPLE DATA 

argv[0] 

User Exit executable 

SQLUEXIT.EXE 

argv[l] 

Function requested 

BACKUP 

argw[2] 

Database drive 

Cr 

argv[3] 

Database name 

MYDBASE 

argv[4] 

Response file 

C:\SqLDBDIR\SQL0C001.BKP 

argvtS] 

Label 

HVDB ASE -684686581 

argv[6] 

Mode 

1 


Table 2: Writing the User Exit in C; interpretation ofARGV army 


Automatic Truncation of Small Log Files 

A third difference is that, for roll-forward 
recovery, log files are truncated and archived 
whenever all database use stops (that is, 
whenever no Start Using Database is in effect for 
that database). Even though the primary log 
file may be configured to hold 100,000 bytes, it 
may be archived when it contains only 30,000. 
Frequent small modifications, with gaps 
between them, could cause a small log file to 
be archived after each modification. This 
would certainly overrun some tape devices 
and could affect system performance 
regardless. To prevent overrun, try a Start 
Using Database in an OS/2 session, perhaps 
using the DBM command-line processor, and 
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int rc; /* return ctfdes from system calls */ 

unsigned char cmd[256]; /* buffer for building OS/2 

1 ' 1 , command strings */ 

int main( int argc, char *argv[ ] ) 

{ 

if( argc != 7 } /* expecting seven arguments to be passed */ 

{ 

exit( FAIL FARM ); 

} 

log_parms( argv ); /* Write input parameters to a *f 

/* history run file */ 

/****##********M***********:M*********:m!m***MM**********:m*/ 
/* Call appropriate routine for function requested */ 

/:m**********t**t******:m**************r*******:m**********#***/ 

if( stricmp(argv[1], "BACKUP") -- 0 ) 

backupC argv ); /* BACKUP function */ 

else if( stricmp(argv[l], "RESTORE") == 0 } 

re$tore( argv ); /* RESTORE function */ 

else if( stricmp(argv[l] t "ARCHIVE") == 0 ) 

archive( argv ); /* ARCHIVE function */ 

else if( stricmp(argv[l], "RETRIEVE") == 0 ) 

retrieveC argv ); /* RETRIEVE function */ 

else 

{ 

/* Write the error to the run file, and exit */ 
log_err("Invalid command option:", argv[1]); 
exit{ FAILJPTION ); 

> 


return( 0 ); 

} 


Figure 7: Writing the User Exit in C: The Main routine 

leave it open throughout the day. This 
precaution prevents small logs from being 
frequently archived. 

Using the User Exit 

A fourth major difference is how DBM is 
instructed to use the User Exit. For Backup or 
Restore, the DBM will call the User Exit if the 
drive specification is zero rather than a letter. 
This is the case whether or not the call is made 
from within an application program, via an 
API, or from DBA Tools, which use the APIs. 
Thus, some Backups can be directed to use the 
User Exit. For roll-forward recovery, on the 


other hand, DBM will always call the User Exit 
if the database is configured to be recoverable. 

It is not possible to specify archiving some log 
files and not others. 

SUMMARY 

User Exit is a powerful, flexible feature that 
gives database users the ability to use storage 
devices not currently supported by the OS/2 
operating system. It is advantageous for both 
large and small databases and can support 
both Backup and Restore and roll-forward 
recovery. 
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/* Small coding example for Backup function using OS/2 XCOPY */ 

void backupt cfiar *parms[ ] } 

/ 


/******************************************************************/ 

/* Expected parameters for BACKUP 

function: */ 

/* 

*/ 

/* parms[G] ; User Exit executable 

"SQLUEXIT.EXE" */ 

/* parms[l] : Function requested 

"BACKUP" */ 

/* parms[2] : Database drive 

"C:" */ 

/* parms[3] : Database name 

"MYDBASE" */ 

/* parms[4] : Response file 

"C:\SQLDBDIR\SQLQQ001.BKP"*/ 

/* parms[5] : Label 

"MYDBASE-684686581" */ 

/* parms[6] : Mode 

"1" */ 

/* 

*/ 

/******************************************************************/ 

unsigned char db_drive[3]; 

/* database drive */ 

unsigned char db_name[9]; 

/* database name (alias if assigned) */ 

unsigned char resp_file[25]; 

/* response file */ 

unsigned char label[20]; 

/* backup label */ 

unsigned char mode[2]; 

/* backup mode */ 

FILE *rf; 

/* respone file handle */ 

unsigned char rsp_line[81]; 

/* respone file line buffer */ 

stropy( db_drive, parms[2] ); 

/* Most of these are not used in */ 

strcpyf db_name, parms[3] ); 

/* this code segment but are shown */ 

strcpy( resp.file, parms[4] ); 

/* to complete the example. */ 

strcpy( label, parms[5] ); 


strcpy( mode, paring [6] }; 


/**********************************************************************/ 

/* Open the response file provided by Database Manager which contains */ 

/* the list of files to be backed up. 

*/ 

/* 

*/ 

/* The Database Manager requires two calls to SQLUEXIT to complete a */ 

/^database backup process. The first can (MODE parameter = 1) request*/ 

/* SQLUEXII to back up the special "UIF" file. The response file would*/ 

/* contain a single line of the form: 

*/ 

/* C:\SQLUTIL\MYD8ASE.UIF */ 

/* 

*/ 

/* The second and final call (MODE = 2) request SQLUEXIT to backup the*/ 

/* directory containing the actual database. The response file would */ 

/* contain a single line of the form; 

*/ 

/* C:\SQL00001\*.* */ 

/.********.*..*********************************************************/ 

if( (rf = fopen(resp_fiIe, V)) == 

NULL ) /* open response file */ 


Figure 8: Writing the User Exit in C; the Backup routine (continued on page 120) 
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{ 

fprintf( run, "\nFailed to open response file: */,s\n M , respJile ); 
exit( FUL_DPEH.RESPOHSE ); 

> 

fgets( rsp.line, 81, rf ); /* get line from response file */ 

fcloset rf ); /* close response file */ 

/**M******#:m*********MH*********t***t*****:m******/ 

/* Build the KOPY command line string to pass to OS/2 */ 
/*:m*****************M**************:m***************/ 

strcpy{ cmd, "KOPY "); 

strcat( cmd, rsp_line ); 

strcat( cmd, " C:\\SQLLIB\\OB_BACKSW 0 ); 

strcat( cmd, db.name ); 

fprintft run, “Backup command = <y p s>\n M , cmd ); 

rc = system[ cmd ); /*pass command to OS/2 and let it do the work */ 

ift rc != 0 } 

{ 

fprintf{ run, "\nFailed system call: , /,s\n ,, J cmd ); 
fprintf( run, " Return Code = Kd\n'V rc ); 
exit( FAIL_GS2 ); 

} 


Figure 8: Writing the User Exit in C: the Backup routine (continuedfrom page 119) 
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LAN 



The LAN Transport Layer of 
Extended Services and 
LAN Services 



by Dana Beatty 

Before LAN Services (LS) and Extended Services 
(ES) came to exist , there urns OS/2 Extended 
Edition (EE). Creating LS and ES was not just a 
matter of splitting EE into two separate packages, 
but rather a metamorphosis that affected the LAN 
Transport layer of these two sendees. 



!TM Token-Ring 
Adapter 


IBM PC Network 
Adapter 


IN THE BEGINNING 

I n the beginning, there was OS/2 Standard 
Edition (SE), OS/2 Extended Edition (EE), 
and IBM's LAN Server. SE provided the 
operating system, while EE contained the LAN 
protocol stacks (NetBIOS and IEEE 802.2), 
some selected LAN adapter card device driver 
support, and the OS/2 requester support. 

LAN Server contained the server and DOS 
LAN Requester functions. 

At the time, there was a logical division of 
functions between the three software 
packages. SE provided an operating system 
base for its PS/2 line of systems that the 
customer could build upon, adding options 
like EE, EE provided a cohesive set of 
protocols, mainly geared towards host 
connectivity, and included LAN protocols that 
allowed APPC to operate over LANs, Finally, 
LAN Server could be added to provide server 
function for local area netw orks. 



Dam Beatty 


In addition to the LAN protocol stack, EE also 
contained the requester function. The obscure 
separation of LAN function between EE and 
LAN Server was hard for customers to 
understand and necessitated purchase of ail 
three software packages (SE, EE, and LAN 
Server) just to operate in a LAN-only 
environment. It also left the bulk of EE 
potential untapped. 

OS/2 was initially designed to support only 
IBM software and hardware. SE, a prerequisite 
for EE, also supported only IBM. Even EE 
initially supported only IBM LAN adapters 
(IBM Token-Ring Network and IBM PC 
Network), not adding Ethernet support until 
version 1,2. Finally, LAN Server was the only 


Figure I: OS/2 Extended Edition LAN protocol stack 
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choice for server support. Figure 1 shows the 
OS/2 EE LAN protocol stack. 

MAKING OS/2 A MORE 
OPEN SYSTEM 

As OS/2 entered the marketplace with this 
system, however, customers were beginning to 
embrace the concept of open systems, 
demanding interoperability from the 
hardware and software of different 
manufacturers. The computer industry quickly 
moved away from closed systems with 
proprietary hardware, software, and protocols 
to shops with a variety of hardware and 
software. For OS/2 to succeed and thrive in 
die future, it had to rise to the challenge of 
interoperability. 


Four major changes were made to bring OS/2 
closer to the open-systems concept. First was 
the notion that IBM's SE need not be the only 
OS/2 base on which services could operate. If 
another vendor's OS/2 version supported 
Compaq hardware, then ES and LS had to 
operate in the Compaq environment. 

The second change incorporated the industry 
standard Network Driver Interface 
specification (ND1S) into the LAN protocol 
stack, or LAN transport layer, common to ES 
and LS. NDtS provides a means for the higher 
layer protocol support in ES and LS to operate 
over OEM adapter cards, as shown in Figure 2. 

The third change was the announcement of 
IBM's sale and support of Novell software. As 
IBM embraced Novell, customers were given a 
choice of servers. 


For OSH to 
succeed and 
thrive in the 
future, it had to 
rise to the 
challenge of 
interoperability. 
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Figure 2: Extended Services and LAN Services IAN transport design 
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A last change was the fact that the LAN 
Transport support and requestor function was 
shipped with ES and LS. This new packaging 
scheme relieved customers with LAN-only 
environments of having to purchase three 
separate products; LAN Services contains all 
the support they need. Additionally, 
customers can now choose to purchase either 
Entry LAN Services or an Advanced LAN 
Services, which includes Entry LAN Services 
plus 386 High Performance File System (HPFS) 
and fault tolerance support. 

Entry LAN Services can be installed on either 
an OS/2 3,E. 130.2 or OS/2 2.0 base, while the 
Advanced LS can only be installed on the 
OS/2 S.E. 130.2 base. 

IMPLICATIONS TO EXISTING 
APPLICATIONS 

Although these are substantial changes, they 
do not affect existing user-written applications. 
If anything, existing programs should benefit 
from performance improvements in the new 
LAN Transport layer of ES and LS, It is 
important, however, to understand that the 
LAN Transport layer provided in LS 2.0 and 
Extended Services vd.4 cannot coexist with 
<7m/ EE version or with ES v.1.3. 
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has written magazine articles for IBM Personal 
Systems Technical Solutions and the IBM 
Personal Systems Developer, has instructed 
system engineers at the Arthur K. Watson 
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at SHARE and GUIDE conferences. She received 
her BA, in computer science from the University of 
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SUMMARY 


The LAN Transport layer of ES and LAN 
Services facilitates a more open OS/2 system. 
When the IBM-only 5E prerequisite was 
removed, these platforms became free to 
operate on non-IBM systems, while the NDIS 
support allows ES and LS to operate over 
vendor adapter cards. 
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LAN 

Creating 32 Bit 
NetBIOS C Programs 



Dana Beatty 


by Dana Beatty 

This article assists developers in creating an 
executable version of the NetBIOS program found 
on the LAN Technical Reference Sample 
Program Listings disk. 


THE NECESSARY INGREDIENTS 

T o ensure that your system has all the 

necessary software ingredients, you may 
have to access the IBM Extended Services (ES) 
for OS/2 2.0 or Lan Services (LS) and the 
OS/2 2.0 Toolkit It is assumed that the 
following hardware and software has been 
installed: 


Files in SAMPLOS2 directory 

NETSAHPO.C 

Sample NetBIOS program source code 

NETERRQR.H 

NetBIOS error codes and message mappings 

NETGBU.H 

NetBIOS sample program global variables 


Figure 1: Files in SAMPLOS2 directory 


* The base operating system OS/2 2,0 plus 
either LS or ES with Communications 
Manager 


* The 32-bit IBM C Set/2 Compiler™. 

Obtaining the Sample Programs 

To program to either the NetBIOS or IEEE 
802.2 application programming interface (API) 
in OS/2, you will need the UN Technical 
Refeixnce manual, available separately from 
OS/2. It contains programming hints, a 
complete list of commands, and the control 
block layout for commands. Included with the 
manual is the Local Area Network Technical 
Reference Sample Program Listings disk 
containing sample dynamic link routine (DLR) 
source code for the NetBIOS and IEEE 802.2 
APIs. While these programs are offered 
without warranty, they provide a good base 
for learning how to program to these APIs. 
Figure 1 lists the NetBIOS files on this disk. 

API Data Structures 

After acquiring the LAN Technical Reference / 
make sure the LAN transport API data 
structures (NetBIOS and IEEE 802.2) have 
been installed on your system. (Refer to the 
appendix for details on loading them.) API 
data structures are available in C, Pascal, and 
assembly language. Figure 2 lists the C 
versions of these structures. 

For OS/2 LS 2.0, these data structures appear 
in the IBMCOM\INCLUDE directory. 


* The LAN transport API data structures Toolkit 


The OS/2 2.0 Programmer's Toolkit 

An OS/2 supported LAN adapter card, 
such as the IBM Token-Ring Network 16/4 
Adapter/A™ or the IBM PS/2 Adapter/A 
for Ethernet Networks™ 


The OS/2 2,0 Programmer's Toolkit contains 
libraries and files that can simplify your 
programming tasks. For example, the sample 
programs on the LAN Technical Reference disk 
rely on the OS2.H file located in the Toolkit, 
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NetBIOS C Programming-Language API Data Structures 

NETB_1_C,H Command and return code defines 

NETB_2_C*H Control block data declarations 

NETB_3_C,H Trace data declarations 

NETB_4_C.B NetBIOS dynamic link routine entry point declaration 

IEEE 802.2 C Programming-Language API Data Structures 

UN_1_C*H Command and return code defines 

UN_2_C ,H Status and error return code defines 

LAN_3_C.H Dynamic link routine general control block data declarations 

LAN_4_CH Dynamic link routine and device driver (DD) data declarations 

LAN_5_CH Trace data declarations 

LAW_6_C. H JEEE 802.2 dynamic link routine entry point declaration 

LA!C7„C.H TYPE declarations 


Figure 2: LAN Transport API f C" programming kngauge data structures 



P ATH=C: \IBMC\BIN - ATH'/, 

set LIB<: \IBMC\LIB; C: \QS2; c: YorOib; '/LIB'/, 

set INCLUDED:\XBMt\INCLUDE;c:\toolkt20\c\os2h;c:\cmlib;XlNCLlfOEX 

set INCLUOE-C: \IBMCQM\INCLUDE; c: \toolkt20\os2bin; V.INCLUDEX 

set TMP-C:\IBHC\TMP 

cd \ibmc\sarnples 


Figure 3: CSETENV.CMD for OS/2 LAN Sendees 2.0 


Setting Up the INCLUDE Path 

Before you can successfully compile the 
sample programs, the compiler must have 
access to all ingredients. Instead of copying 
them into the directory containing the 
compiler and the source code, it is easier to set 
the INCLUDE path and LIB path. 

When you install the IBM C Set/2 compiler, a 
file called CSETENV is created. Ensure that 
this command file sets a path for the LAN 
transport API data structures and the toolkit 
include files. 

Figure 3 shows a sample command file which, 
when executed, will set the INCLUDE path so the 
compiler can locate key files, such as OS/2.H 
and the LAN API data structures. 


COMPILING THE 
SAMPLE PROGRAM 

Once you have acquired all the necessary 
ingredients, you can create MAKE and DEF files 
to compile and link the sample programs. 
Newer releases of the sample program disk 
should already contain these files. Begin by 
creating a MAKE file called NETSAMPO.MAK 
and enter into it the statements shown in 
Figure 4. 

Next, create a link definition file named 
NETSAMPQ.DEF and enter the statements shown in 
Figure 5. The definition file will resolve 
program calls to the LAN Transport NetBIOS 
interface. 
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Minor 
modifications or 
enhancements 
can be made to 
the sample code 
to provide 
solutions for real 
customer 
situations. 


netsaiflpo.exe : netsampo.obj 
LINK 

netsampo.obj,netsampo.e x e,,,netsampo *def 

netsampo.obj : netsampo«c 

CC netsampo.c,netsampo.obj; 


Figure 4: NETSAMPO.MAKfile 


IMPORTS 

ACSNETB.NETBIOS 


FigureS: NETSAMPO. DEF file 


In preparation for compiling the programs, 
issue the CSETENV command. Then copy the 
NetBIOS sample programs from the LAN 
Technical Reference disk to the 
IBMCNSAMPLES directory. 

If you wish to compile the sample program as 
a 32-bit version, you must take an extra step, 
editing NETSAMPO.C and inserting " #define 
E32TD16" at the top of the file. This allows the 
compiler to use 32-bit include files. To compile 
the program issue the command: 

NHAKE NETSAMPO.MAK 


SUMMARY 

With these leads, you can quickly create an 
executable NetBIOS program from the sample 
code on the LAN Technical Reference Sample 
Program Listings disk. Once this is done, 
experimenting with the NetBIOS API is easy. 
Minor modifications or enhancements can be 
made to the sample code to provide solutions 
for real customer situations. 


APPENDIX 

Loading the API Data Structures 

For IBM LAN Services for OS/2 , the API data 
structures should automatically be loaded into 
the IBMCOMNINCLUDE directory during 
installation. If, however, the directory is 
empty, you may have failed to perform the 
shutdown as instructed by the installation 
program. Check to see if another system on 
your network, such as the server, has these 
data structures. Otherwise, reinstall LAN 
Services. 

For IBM Extended Services for OS/2, the API 
data structures are loaded via the "Install 
Additional Features" panel of Communication 
Manager. 


This should compile and link the sample 
program, creating an executable file named 
NETSAMPO.EXE. 

RUNNING THE SAMPLE 
PROGRAM 

To obtain a list of options for the sample 
program, enter: 

NETSAMPO ? 

To test the program, open two OS/2 sessions 
with one acting as the receiver (RECV) and one 
as the sender {SEND}. 


Dana L. Beatty, IBM, 1000 N. W. 51st St. f Boca 
Raton f Fla. 33432. She is a staff programmer in the 
Communications Subsystem Development l 
department for IBM Entry Systems Technology in 
Boca Raton , Fla. She joined IBM in 1985 and 
worked on applications written to the IEEE 802.2 
API. Beatty has written magazine articles for IBM 
Personal Systems Technical Solutions and the 
IBM Personal Systems Developer, has 
instructed system engineers at the Arthur K. 
Watson International Education Center , and has 
presented at SHARE and GUIDE conferences. She 
received her BA. in computer science from the 
University of Texas, Austin . 
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Communications Manager 

Hyperaccess/5 and OS/2 
Multitasking Communications 



by M. Keith Thompson 

Hyper ACCESS/5™ (HA/5), from Monroe, Mich, 
based Hilgraeve Inc., provides asynchronous 
communications for OS/2 and DOS. HA/5 
provides developers and users with high-speed file 
transfers, extensive terminal emulation, built-in 
modem support, and innovative virus protection. 
With a powerftd scripting language and remote- 
control capability, HA/5 offers deivlopers 
automated multitasking communication sessions 
and an easy support mechanism. 

S ince 1985, HyperACCESS has been a 
powerful communications tool for 
business PCs. The current release supports up 
to 175 modems and serves many other 
functions, HA/5's recent update is joined by 
an upcoming GUI version for Windows and 
OS/2 2.0. 

HA/5 is currently the only full-featured 
communication program available for OS/2, 
supporting interfaces such as COM1 through 
COM4 on ISA machines, COM1 through 
COM8 on PS/2 models, user-defined 
interrupts on COM3 and COM4, OS/2 
communication devices, and INTI4 networked 
modems. With Hayes' Enhanced Serial 
Interface™ (ESI) and OS/2, HA/5 can talk to 
modems at up to 57,600 bits per second. 

One of HA/5's chief strengths is its 
straightforward, quick, and easy-to-use menu 
structure. The sliding menus allow you to use 
either the point-and-shoot method or speed 
keys to access features. 

HA/5 works particularly well as a common 
communication program for DOS and OS/2 
users. You can master HA/5 on one platform 


and communicate with it or other 
communications programs on either DOS or 
OS/2. 

The program also provides users of older PC's 
(8088 and 80286 based) with reliable, high¬ 
speed file transfers, allowing the older PCs to 
work with the new class of V.32bis modems 
operating at DTE speeds of up to 57,600 bps. 

FEATURES 

HA/5 offers developers options beyond those 
traditionally found in asynchronous 
communication software, fulfilling three 
communications functions with its mini 
Bulletin Board System (BBS), Remote Host 
mode, and E-Mail system. For example, a 
software company could set up a BBS for its 
users, who could call in for software updates 
and technical support, Using the same 
program for all communications needs 
eliminates the need to learn multiple 
programs, 

Terminals 

HA/5 offers an extensive terminal emulation 
set. The 17 terminals it emulates, which 
provide access to almost any host, include: 


VT-52 

* IBM 3101 and 3278 

VT-100 

• ANSI 

VT-102 

. tty 

VT-220 

* ADM3 A 

VT-320 

• VIEWPNT 

TV925 

• WANG 

TV950 
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All terminal emulators offer support for 
function and other editing keys, while the TV 
and IBM 3101 emulations offer protected fields 
and block mode, HA/5 supports AT&T and 
Northern Telecom ISDN terminal adapters. 
Figure l shows the HA/5 character mode 
interface. 

Protocols 

HA/5 protocols have been independently 
tested and found to be the fastest and best 
implemented of all asynchronous 
communications programs. HA/5's protocols 
include: 



Press first leUer of option or ESC to leave menu 


jfrUail for data calls 

Em I carrier ro allow a voice call to switch to data 
Cable to another computer and act as hast 
Redefine the modern and moden port 
Log activity in AHSUER.LOG 

Display messages in other OS/2 tasks when calls arrive 
Manage (he password list 


Marne Rd Ur OuWr Pm FilKgt AnyDir OS/2 CalBak Pgris 

..<t»one> X X X X X X X . X 

...<none> XX.. . X _ . X 

_..Audry Farher XX.. , X 

.Gordon Gray XX.. . X . X X 

_lie I on ie Haber X X . X . X X X 

i.Nick Danger XXX. X . . . X 

Stiles CalJierwood XX.. X X X 


Password 
unlim t. _ _ 
limit..... 
bti fami ta.. 
(jomediga.. 
Komefaoe., 
eyeelauirrs 
cogameki.. 


IT, 

SI 

m 


If# 

• 

i 

0 

IBB! 





Views 




F.T-l-l 

T.I.I.I 


© 

is. 

<uii 

i 

HI 

■ 
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Figure 1: HA/5 character mode interface 

* HyperProtocol™ (available in 
the public domain) 

* Zmodem 

* Ymodem 


HyperProtocol, the most efficient of the group, 
offers additional throughput by utilizing an 
LZW-based software compression routine 
during file transfer. 

HypcrPilot 

HyperPilot™, HA/5's scripting language, 
offers over 150 commands that control 
virtually all the functions and parameters of a 
communications session. The HA/5 user 
manual includes a short tutorial and a 
complete command listing of HyperPilot, a 
procedural program with a programming 
structure that closely resembles that of C. The 
latest version, HA /5 2.1, includes scripts for 
accessing remote on-line systems such as MCI 
Mail, CompuServe, GEnie, and BIX. 

As in a C program, HA/5's scripts reside in a 
standard text file with an .HP file extension. 
This allows you to use the editor of your 
choice to write the scripts. HA/5 also records 
keystrokes and stores them in a script file for 
later use. Before it runs the script, H A/5 
compiles the source code into machine code 
that can be more quickly executed. 

BBS 

HA/5's BBS offers upload and download 
capabilities. Through passwords, a system 
administrator controls which functions each 
user can access. Some users, for example, 
might only be able to upload files to the host 
computer, while others could run programs on 
the host. For added security, HA/5 includes a 
callback feature that allows the host computer 
to call a remote user at a predetermined 
number when the user enters a password. This 
feature consolidates all long distance 
telephone charges at one central location, 

E-Mail 


* Ymodem G 

* Ymodem Batch 

* Xmodem 

* IK-Xmodem 

* Xmodem CRC 

* Xmodem Checksum 

* CompuServe Quick B 

* Kermit 


HA/5's E-Mail system, like its BBS, is a 
downsized version of a complete product. The 
E-mail feature allows users to send and receive 
messages within a user group. Together, E- 
mail and the BBS compose a practical technical 
support system. Figure 2 shows BBS options in 
HA/5. 

Extended Hardware Buffering 

With OS/2 1,2, IBM and Microsoft added 
extended buffering to the 16550 UART in 
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PS/2s and other high-end PCs. This provided 
two benefits to users: more reliable high-speed 
communications and better response time for 
foreground applications while 
communications sessions run in the 
background. While not all communications 
programs can use the 16550's capability, 

Hyper Access recognizes the 16550 and turns 
on its buffering capability, allowing HA/5 to 
operate more efficiently in the background. 

The user sees a decrease in response time 
during background file transfers with a 
normal UART due to the workings of serial 
communication. High-speed serial 
communication requires a substantial amount 
of CPU power. Each time a character comes in, 
the serial port interrupts the CPU with a 
request for service. With the 16-byte FIFO 
buffer turned on in the 16550, the CPU gets 
interrupted only one sixteenth as often as 
before, leaving more computing power to the 
foreground application. 

Remote Control 

HyperACCESS/5 is the only general-purpose 
communications program to deliver cross¬ 
platform compatibility for remote control. If a 
DOS remote PC with HA/5 calls an 05/2 host 
PC with the remote host mode, each computer 
can execute programs on the other. With the 
remote host, a programmer can control remote 
PC applications and operating-system 
software. In addition, HA/5's Learn Mode can 
watch, decipher, and optimize remote 
communications sessions as compiled scripts 
for later use. With its acquisition of 
KopyKat™, Hilgraeve is the only vendor to 
offer remote control under OS/2 PM. 

A text editor, included with HA/5, offers full¬ 
screen editing capabilities with block move 
and delete features. Additional features 
include split-screen editing of two files and 
search and replace. It is also possible to 
substitute another editor or word processor. 
Remote system icons for HA/5/PM are shown 
in Figure 3. 

OS/2 

While these features are available under DOS 
as well as OS/2, HA/5 includes extra 
functionality specific to OS/2. With OS/2's 
multitasking, users can perform file transfers 


as background tasks while doing other work in 
the foreground, HA/5 for OS/2 also supports 
m u 11 i pie conimun ica ti ons sessi ons, alio w ing 
users to work on two or more hosts at once. 

CPU Utilization 

H A/5's aggressiveness setting controls how 
much CPU time a communications session 
receives. While OS/2's preemptive 
multitasking allows applications to vie for 
processing time, HA/5 optimizes the 
multitasking environment by adjusting the 
aggressiveness setting. With a low setting, the 
foreground application takes priority and 
utilizes more CPU cycles. 






l strnsterev 




HtwncMS 




Figure 2: BBS options in HA/5 


HA/5 for OS/2 allows a user to start other 
OS/2 sessions as child processes and run 
communications detached. Running H A /5 as 
a detatched process, another option, requires 
less CPU time and memory, but doesn't allow 
keyboard control or display* Placing 
automated calls or answering calls are 
examples of detatched usage. 

HA/5 uses shared modems on LAN Server 
and LAN Manager networks. Instead of 
entering the usual COM1 through COM4 in 
the setup screen, you enter the server and 
queue name of a modem located on another 
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PC. The server and queue name use the 
standard UNC (Universal Naming 
Convention) type name \\<server>\<cjueLje>. 

The OS/2 version of HA/5 includes an extra 
diagnose utility. The /D option, represented 
graphically as a stethoscope on the PM 
Desktop, collects data to assist Hilgraeve in 
reproducing any errors or protection 
violations. If errors occur while HA/5 is 
running, you copy the information in the 
DIAGNOSE subdirectory to a disk. Armed 
with this data, Hilgraeve technical support can 
help you isolate the problem. 



Virus Filter 

Proactive virus detection with HyperGuard™ 
provides an excellent defense from today's 
numerous viruses. During file transfers, H A/5 
filters incoming data for known virus 
signatures. When a virus is detected, HA/5 
displays a warning message and gives you the 
option to abort the file transfer and delete the 
existing portion of the file from the disk. To be 
sure the virus does not cause any trouble, 
HA/5 writes all zeros to the file before 
deleting it. HyperGuard, which uses the same 
set of virus signatures as IBM's Vims Scanning 
Program™, currently recognizes 315 viruses. 


The virus signature file is easily updated from 
Hilgraeve s BBS or IBM's V1RUS.LST. 


CASE STUDIES 

Fifield Carp . 

Fifield Corp., a Chicago-based commercial 
property management organization with six 
field offices across the U.S., launched a project 
to automate its accounting functions. Fifield 
discovered that it could save significant 
worker time and money by providing on-line 
access to accounting data with H A/5. 

Chuck Hinderliter, Fifield's system network 
coordinator, manages and maintains all 
network functions. The network includes IBM 
PS/2 Model 80s for file servers and Model 55s 
for client PCs. The client PCs run DOS and 
OS/2 over the OS/2-based 3Com 3+Open 
network. 

Fifield's first goal was to provide, on a server 
at the hub of its network, a secure centralized 
accounting database. The company chose a 
Timberline™ accounting system because of its 
multitasking capabil i ty under OS / 2. Before 
Fifield adopted HA/5, problems arising at the 
field offices meant that technical support staff 
from the central office had to go on site to 
troubleshoot. 

With HA/5's remote host access and scripting 
features, Fifield's remote offices now have 
automated communications with the central 
office accounting database. The company 
reduced their data transmission time from 15 
to two hours a week and simplified the file 
compression process by replacing external file 
compression utilities with Hyper Protocol file 
compression. Using HA/5's remote control 
feature, support staff can perform diagnostics, 
solve problems, and run system backups on 
remote computers, thus reducing down time 
and travel expenses. 

Countrywide Funding 

Countrywide Funding, a full service mortgage 
banker with 100 offices across the country, 
needed a simple, easy way to communicate 
with its 350 PCs, They chose HA/5 due to its 
powerful scripting language, OS/2 support, 
and good technical support. 
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Hyper ACCESS /5 now handles all of 
Countrywide's communications from 
checking electronic mail services to polling 
branch offices to accessing government 
agencies. Using HA/5's scripting language, 
Countrywide created a custom interface to 
front end all of its communications services for 
novice users. 

Monroe County Pure Wafers 

The Monroe County Pure Waters agency, 
which governs local water use in Monroe 
County, New York, needed to tie together its 
county-wide computer system. The agency 
needed to collect data from computers 
monitoring plant operations located 
throughout the county and assemble it at the 
administrative hub. 

After evaluating several methods of data 
collection. Pure Waters chose OS/2 and the 
Hyper ACCESS/5 communications program. 
OS/2's multithreading and background 
processing combined with HA/5's custom 
features and ease of use have made data 
collection simple and fast. 

Supervising accountant John Chase used 
HA/5's script language, HyperPilot, to run file 
transfers at predesignated times. For the 
agency's field employees, Chase created a 
custom system interface. He also developed a 
corporate BBS with HyperPilot, providing 
agency users with access to company 
information. 

Pure Waters uses HA/5 to handle remote 
diagnostics, system updates, and maintenance, 
eliminating many field support expenses. 


H A/PM uses OS/2 2.0 to execute instructions. 
With preemptive multitasking, commun¬ 
ication intensive tasks operate in the 
background without noticeably affecting 
foreground session performance. Tasks are 
stored as threads instead of message loops, 
requiring the fewest possible CPU cycles. 

By using PM's dynamic data exchange 
capability, HA/PM can share data with other 
communications sessions and applications 
such as databases, spreadsheets, and word 
processors. For example, a developer can 
simultaneously capture real time data from an 
application on a remote computer and analyze 
the data using another program. 

Both of the upcoming GUI versions include 
Hilgraeve's new Modular Communications 
Engine (MCE), The MCE provides faster 
throughput for multiple communications 
sessions by separating low-level I/O 
processing from other communications tasks. 

It services the communications medium in real 
time while other portions of the program 
service the display and keyboard. With this 
new modular technology, developers can 
focus on creating custom applications. 

CONCLUSION 

Hilgraeve's HA/5 combined with OS/2 
creates an asynchronous communications 
environment with features such as virus 
filtering, a scripting language, remote host 
operation, and electronic mail. HA/5, the only 
full-featured communications program for 
OS/2, provides all the functionality of its DOS 
program in an easy-to-use product. 



With preemptive 

multitasking , 

communication 

intensive tasks 

operate in the 

background 

without 

noticeably 

affecting 

foreground 

session 

performance. 


Keith Thompson is a communications consultant 

HYPERACCESS FOR OS/2 2,0 based in Florida. He is a frequent contributor to 

computer publications. 

Hilgraeve is currently testing new versions of 
Hyper Access for Windows and PM for release 
later this year. The 32-bit PM version is 
designed specifically for OS/2 2.0, with tested 
DTE speeds up to 57,600 bps. 

H y p er Access / PM (HA/PM) ta kes a n ob j ect 
oriented approach to communications. While 
traditional communication programs allow 
users to choose entries from a dialing 
directory, HA/PM displays remote systems as 
selectable icons in a window. 
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System Application Architecture 

CCL/2: A User Interface 
Migration Tool for OS/2 2.0 



Ruth Aww Taylor 


by Ruth Anne Taylor 

If you have worked with OS/2 2.0 , you have had a 
chance to use the CUA 93 controls. Have you 
wondered how these controls can be used in OS/2 
13 or Windows 3.0 applications? IBM SAA CUA 
Controls Library/2 t or CCL/2, is your answer. 

CCL/2 is a productivity tool that embodies the 
C Li A user interface architecture, using a set of 
dynamic link libraries that contain the controls in 
16-bit OS/2 13 and Windows 3.0 environments. 
These libraries may be incorporated directly with 
the application code, allowing the developer to focus 
more on the content and quality of the application 
rather than on CL/A conformance. 
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Figure 2: Value set, slider controls, and container control 
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WHAT IS THE PURPOSE OF CCL/2? 

I n support of its goals to make OS/2 2.0 the 
development platform of choice and to 
make the new CUA architecture pervasive 
across multiple operating system 
environments, IBM provides migration 
support for OS/2 1.3 and Windows 3.0 
applications through graphic user interface 
controls that conform to the CUA 91 
architecture. The controls, including the 
container, file dialogue, font dialogue, 
notebook, spin button, slider, and value set, 
are packaged on 3,5* and 5.25-inch disks for 
OS/21.3 and Windows 3.0. CCL/2 controls in 
these environments work like those in the 
OS/2 2.0 base system. The spin button, already 
a part of OS/2 1.3, is provided in CCL/2 only 
in the Windows 3.0 format. 


CCL/2 CONTROLS 

In Figure 1, the value set and slider controls 
are displayed in the left window. The 
container control is shown in the right 
window. 

Figure 2 shows the notebook, value set, and 
slider controls. 

Container Control 

The container control, a key component of the 
CUA Workplace Model, is used to group 
related objects for easy access and retrieval 
and to present objects in various views. Each 
view generally provides different information 
about an item. 

The icon view presents the container items in 
an iconic format with text beneath the icons. 
Generally, an icon represents the item type. 
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The name view presents the container items in 
an iconic format with text to the right of the 
icons. It can appear either as a single column 
list or as multiple columns of the same type of 
data. 

The text view presents a simple text list of the 
contents, and can appear in either single or 
multiple columns. 

The tree view presents a hierarchical view of 
the container items. Three types of tree views 
are available: tTee icon, tree name, and tree 
text. 

The details view presents information about 
each container item, arranging information 
about that item in columns. 

File Dialogue 

The file dialogue provides a modal dialog that 
allows applications to consistently perform file 
operations such as open and save, implemented 
as either Open or Save As... dialogue. 

The standard file dialogue includes basic 
functions that can be extended to meet the 
requirements of an application. They give 
users the ability to: 

* Display and select from a list of drives, 
directories, and files 

* Enter a file name directly 

* Filter the file names before they are 
displayed 

* Display active network connections 

* Specify extended attributes for TYPES {for 
OS/2 Version 1.3 only) 

* Interact with a single-selection or multiple- 
selection file dialogue. 

Font Dialogue 

The font dialogue provides a dialogue that 
allows applications to consistently view and 
select font family names, styles, and available 
sizes. In the font dialogue, the family name is 
the name of the typeface. Courier, Times, and 
Helvetica are some commonly used family 
names. Type styles include normal, bold, italic, 
and bold italic. Size is the point size, or vertical 


measurement, of the type. Font emphasis 
styles include underline and strikeout. The 
font dialogue provides basic functions that can 
be extended to meet the requirements of an 
application. They give users the ability to 
display and select from a list of: 

* Font family names installed on the system 

* Styles for each font 

» The available sizes for each font 

* The emphasis styles available for each font. 

In addition, users can view their selections in a 
preview area, using a sample character string, 
and can interact with a modal or modeless font 
dialogue. 




Notebook Control 

The notebook control simulates an actual 
notebook, which can be used to organize 
information in list or calendar format. Related 
pieces of information can be organized into 
sections, divided by theme, and represented 
by text or icon. Sections are marked with tabs, 
by which the user can navigate from section to 
section. 

Slider Control 

The slider control supports the setting of 
approximate values and properties in analog 
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rather than digital form, while providing 
visual feedback on the extent of a value within 
a range. The slider control emphasizes fluid 
control and is best used to modify settings 
rather than to select exact numerical values. In 
many applications, the slider control can 
replace awkward use of the scroll bar* 

Spin Button Control 

The spin button control is used to display one 
data value at a time by scrolling through a list 
ota v a i la bled a t a .The sp i n b u tto n m od el 
should reflect real-life objects such as stereo 
knobs, TV channel knobs, or oven temperature 
dials. CCL/2 provides the spin button control 
on 1 y for VV indows 3.0, as it i s al read y i n cl u d e d 
in OS/2 13. 


WHO NEEDS CCL/2? 

CCL/2 addresses the user interface 
development needs of application developers 
creating programs for OS/2 1.3 and Windows 
3.0, and provides tools for conformance to the 
CUA 91 architecture across these platforms. 
CCL/2 will offer assistance in migrating these 
applications to OS/2 2.0 due to the similarity 
between the controls' programming interfaces 
and the new CUA APIs in OS/2 2.0. Reusable 
code that can be shipped directly with the 
customer's applications increases productivity 
Details concerning which portions of CCL/2 
can he redistributed with the developed 
application are specified in the license 
information shipped in the program package. 


CCL/2 relieves 
application 
developers of 
significant 
user-interface 
development 
efforts and 
allows for 
concentration 
on competitive 
functions. 


Value Set Control 

Tlie value set control allows the user to select 
one value from a finite set of graphic images 
supporting the display and selection of 
choices, which can be represented graphically, 
numerica 11 y, or te\tuallv. Choices w i th in a 
particular value set can also be changed. The 
graphic images of the value set also preserve 
screen "real estate. 1 ' Selecting one choice from 
a range of alternatives automatically cancels 
any previously active choice. 

Refer to IBM Personal Systems Developer, Winter 
1992, for detailed articles on the use of each 
control. 


CCL/2 CONTENTS 

Sample applications for OS/2 1.3 and 
Windows 3.0 environments enable application 
developers to quickly learn the controls. 
CCL/2 also contains sample application 
source code and the files necessary to build the 
applications. 

Th e P rogfim \ n i h ig G 11 ide , Prog Tam nitJg R eferei ice 
for OS/2 Presentation Manager f and the 
Programming Reference for Microsoft Windows 
are included in OS/2 L3 and Windows 3.0 
help formats for use online as well as in the 
manuals. The QuIckHelp™ program, included 
with the Microsoft C compiler, allows 
developers to access technical information 
while writing an application. 


PROTECTING INVESTMENT 
AND STAGING GROWTH 

The similarity of CCL/2 to the CUA 91 
architecture constructs in OS/2 2.0 increases 
the opportunity to develop code that can be 
more easily migrated to OS/2 2.0. Those 
customers who plan to migrate to OS/2 2.0 
with near term OS/2 13 or Windows 3.0 
development can easily position their 
application for migration. Because those 
portions of applications developed for OS/2 
13 and Windows 3.0 that use CCL/2 will run 
on OS/2 2.0, organizations can expand 
technically as their business needs change. 

SAVE TIME AND MAKE 
YOUR JOB EASIER 

CCL/2 relieves application developers of 
significant user-interface development efforts 
and allows for concentration on competitive 
functions. The CCL/2 controls simplify 
conformance to the CUA 91 architecture for 
05/21.3 and Windows 3.0, while consistent 
CUA Controls APIs provide easy application 
migration from OS/2 1.3 and Windows 3.0 to 
OS/2 2.0. 

CCL/2 is designed to allow developers to 
maximize productivity when developing 
applications that conform to the CUA 91 
architecture. This productivity gain can be 
realized through reusable components that 
employ the CUA 91 architecture. Packaged as 
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CHANGING THE VIEW OF A PRESENTATION MANAGER CONTAIN ER 
CNRINFD cnrlnfo; 

/*********************************************************************/ 

/* Set the attribute field to the icon view* */ 

/*********************************************************************/ 
cnrlnfo.flUindowAttr = CV_IC0N; 

y****************************************************************+****/ 

/* Change the view from the current view to the icon view* */ 

/*********************************************************************/ 
WinSendMsg( 

hwndCnr, /* Container window handle */ 

CM^SETCNRINFD, /* Container message for setting */ 

MPFROMPUcnrlnfo), /* container control data */ 

MPFROMLQNG(CMA_FLWINDOWATTR)); /* Message attribute that sets */ 

fa container window attributes */ 


CHANGING THE VIEW OF A WINDOWS CONTAINER 
CNRINFO cnrlnfo; 

^*********************************************************************/ 
fa Set the attribute field to the icon view. */ 

/*********************************************************************/ 
cnrlnfo.flUindouAttr - CV_ICQN; 

y*********************************************************************y 


fa Change the view from the current view to the icon view* */ 

/**************************#****************************+*+*+*********/ 
SendMsgf 

hwndCnr, /* Container window handle */ 

CH_SETCNRINFO, /* Container message for setting */ 

/* container control data */ 

CMA _FLWIN DOW A TTR, /* Message attribute that sets */ 

/* container window attributes */ 
(DWORD)(IPVOID)feenrlnfo); fa Container control data */ 


Figure 3: Code samples showing ease of migration 


dynamic link libraries, portions of CCL/2 can 
be shipped directly with the developed 
application* The License Information shipped 
in the program package specifies which 
portions can be redistributed with the 
developed application* 

Additionally, CCL/2 is structured to conform 
to the same APIs found in OS/2 2,0, which 
reduces rework in migrating CCL/2 
applications from OS/2 13 or Windows 3.0 to 
OS/2 2.0, The APIs for CCL/2 in OS/2 13 are 


the same as the CUA Controls in OS/2 2*0, but 
due to differences between OS/2 Presentation 
Manager and Windows, the APIs for CCL/2 in 
Windows 3*0 are similar to those in OS/2 2*0* 

Figure 3 contains the sample code necessary 
for changing the view of the container control 
using OS/2 1.3 Presentation Manager and 
Windows 3.0. 

In CUA 91, objects represented by controls and 
icons mimic objects in the real world, allowing 
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the user to move comfortably in the computer 
environment and to reduce time and errors, 
thus concentrating on the task at hand, CUA 
conformance, along with providing the 
benefits specific to adopting CUA 91 
architecture, ensures user interface consistency 
between applications. 

Consistency across applications and 
environments helps the transfer of knowledge 
from one product to another, yielding savings 
in user training. CCL/2 helps stretch this 
consistency to OS/2 1.3 and Windows 3,0. 

CONCLUSION 

Using these controls will allow you to develop 
programs that conform to the application 
orientation of the CUA 91 architecture for both 
OS/2 1.3 and Windows 3.0. The consistency of 
the CCL/2 interfaces with the new APIs in 
OS/2 2.0 allows user-interface migration with 
minimal rework, 
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No Matter What Your GUI Destination 


CASEWORKS 

Can Take You There 



Now You Don’t Have to Worry About Choosing the Wrong GUI Development 
Path...CASEWORKS Lets You Easily Change Direction — by Switching 
Languages or Platforms — Without Wasting Any Timet 


All of the choices surrounding Graphical User Interfaces 
(GUIs) can make picking a GUI development path seem 
impossible. Deciding between Windows™ or Presenta¬ 
tion Manager™ (PM) is only the first step toward building 
client/server applications. You need a tool that lets you 
generate code to Windows or PM for a variety of languages 
and APIs, and that lets you migrate interfaces among 
languages and platforms if you change your mind. 
CASETU™ and CASE;PM ] M are the only tools that give you 
that flexibility. 

CASE:W for Windows Development 

Windows developers face the challenge of migrating 
from C to C++ and class library programming, CASE:W 
makes it easy by generating source code for the three 
"standards" of Windows programming: the Windows C 
API. Microsoft Foundation Classes™ and Borland’s 
ObjectWindows™, 

Simply buy CASE:W r along with a “Knowledgebase" 
for C or Ct+ and a class library. Use the visual designer 
to create and test your interface. Then generate expert- 
level, tightly-written, thoroughly-documented code from 
your knowledgebase. To use the interface in a different 
en vi ro n m en t, s i m ply bu y t h at kn o w led ge bas e an d ge ne rat e 
again. You can even migrate the interface to PM. 


CASE: PM for Presentation Manager Development 

When you're developing “mission-critical" applications 
for OS/2 ™2 + 0 f you need a strategic tool that can build PM 
applications for both 16- and 32-bit PM environments. 
Our new CASE:PM VIP tool gives you a head start on 
building client/server applications, and lets you easily 
migrate legacy applications to OS/2 2.0. Plus, you can 
leverage all the advanced capabilities of CUA 91. 

The Safest Development Route 

With CASEWORKS, you get the security of using the 
leading GUI development tools, Microsoft M includes a 
version of CASE:W with its QuickC ™ for Windows, and 
more corporations use CASE:PM for developing strategic 
PM aadclient/server applications than any other standard 
language tool. Both tools generate code without 
restrictions, let ting you add any code, anywhere. Plus, a 
regeneration facility preserves your changes. And you 
control the generated code, with no proprietary 
languages, runtimes or licensing fees. 

Don’t avoid making a decision because you’re un¬ 
certain which way to go. Choose the only company that 
can take you to Windows or PM. through any develop¬ 
ment route: CASEWORKS. 


CASEWORKS" 

A A A A 

i Dunwoody Park. Suite 130, Atlanta, GA 30338 
1-800-635-1577 • (404)399-6236 • Fax (404) 399-9516 







Windows and OS/2 
have in common? 





Object Vision lor Windows ObjectVision for OS/2 

A:Ybur ObjectVision applications. 


Borhiml's ObjectVision brings Microsoft 
Windows and OS/2 users together. Only 
ObjectVision allows you to unite an appli¬ 
cation once lor use under both Windows 
and OS/2. And seamlessly access the 
same data, regardless of platform. That's 
because ObjectVision, the world s easiest 
tool for creating Windows applications, is 
now also available for OS/2. 


Visual programming 
makes it easy 

Using revolutionary 
visual programming 
techniques, Ol ijectVision 
makes it easy for the 
people w ho know the 
business issues to develop 
and maintain their own 
graphical software 
applications without 

Tied: #1 Application Software 

Pubfislierin Costumer Satisfaction" pn*gl HUUUmg. 



Creating Windows or OS/2 applications is 
as easy as A-B-C. Simply; 

A, Draw your application interface using 
the convenient form tool. 

Bp Apply your business rules visual I v. 

C. Connect your application to your 
existing database. Or create your 
own database. 

In Windows and OS/2, ObjectVision makes 
it easy to create, modify and run your own 
interactive applications. And the OS/2 ver¬ 
sion giv es you easy access to REXXas well 
as DLLs/ 

Easy access to data 

ObjectVision is the ideal front end to your 
data because it integrates information from 
different databases under one familiar, 
graphical user interface. Your ObjectVision 
applications can easily connect to informa¬ 
tion stored in Paradox,* dBASE* Btrieve, 
Database Manager and ASCII formats. 


FREE runtime version 

Because a runtime version is included 
free, it’s easy to distribute your customized 
applications throughout your company. 

With ObjectVision, fully interoperable 
Windows and OS/2 applications are 
here today! 

I"" See your dealer today t^et your own* ^ 
copy of ObjectVision for Windows or OS/2, 

I OR call 1-800-331-0877, ext. 6601 to 

■ request your ObjectVision for Windows ■ 

FREE TRIAL DISK 


In Canada, call 1-800-461-3327 



BORLAND 

The Leader in Object-Oriented Programming 

Copyright * 1992 Borland International, Inc. AH rights reserved. ObjectVision. Paradox and dBASE are registered trademarks of 
Borland International, Ino, OS/2; is a registered trademark of I0M. Microsolt Is a registered trademark of Microsoft Corporation, 

M991 J.D, Power and Associates 1991 Computer End User Satisfaction Study for Application Software Publisher. Phase IV: 

Business End User Summary Responses from Business End Users at 4.396 business sites. Bl 1552 
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